Re: [Doxygen-users] Problems with Python code
Brought to you by:
dimitri
Menu
▾
▴
Re: [Doxygen-users] Problems with Python code
|
From: Dimitri v. H. <di...@st...> - 2005-07-28 19:43:06
|
Hi Thomas,
I've corrected your example below, but please note that
there are still several issues with documenting Python code (I mainly tested
using undocumented code). I'm in the process of fixing these problems and
adding examples to the documentation, so it will be more clear how to document
Python code. Initially it be a little more restricted than documenting
other languages. I think it is best to wait for the next CVS update.
Regards,
Dimitri
On Thu, Jul 28, 2005 at 01:40:25PM +0200, Thomas wrote:
> Hello!
>
> I want to use doxygen (1.4.4) for documenting python code. I use
> following simple python script to test it:
>
> ## \file c.py
^^^^^ This should be removed, doxygen recognises module documentation
and will translate it to a namespace internally.
> ## \brief A documented file
> ##
> ## This is the detailed file description
>
> ## A class with doxygen remarks, only
> class pure_doxygen:
>
> ## Constructor of pure_doxygen
> def __init__(self, value):
>
> ## The desc of var1
> ##
^^^ This is not (yet) supported. You need a documentation block
at class (indent) level, which contains a @var command for this.
> self.var1 = 3
>
> ## The foo1 method
> ## \param self The class itself
> ## \param bar An test parameter
> def foo1(self, bar):
>
> ## The desc of var2
> self.var2 = 6
> self.var3 = 9 ##<The desc. of var3
^^^ not supported yet.
>
> class pure_python:
> """ A class with python docs, only """
>
> def __init__(self):
> """ Constructor of pure_python """
> self.var4 = 3
>
> def foo2(self, bar):
> """ The foo2 method """
> self.var5 = 6
> self.var6 = 9
>
> # End of c.py
>
> When I use a doxygen config file with no INPUT_FILTER and
> FILTER_SOURCE_FILES = NO, I get the 'c::pure_doxygen Class Reference'
> which you can see as html in try1.html (I haven't attached the
> doxygen.css file, so the output looks poor. Here only the content is
> important).
>
> There are several problems:
> 1.
> The function foo1 is described as:
> Public Member Functions
> def foo1
> The desc of var1 The foo1 method.
>
> But "The desc of var1" is not the description of foo1 but of self.var1
> variable!
>
> 2.
> def c::pure_doxygen::__init__() [private]
>
> Where are the parameters self and value from the source code? How to
> document them?
>
> 3.
> None of the 'self.' variables is documented. Why?
>
> In the 'c::pure_python Class Reference' (try2.html) are the same
> problems like above. Additionally self.var4 is documented, but wrong:
> Member Data Documentation
> c::pure_python::var4
> Constructor of pure_python
>
> var4 is not the constructor of pure_python!
>
> I searched a lot in different newsgroups and found some hints to use
> pythfilter.py from http://i31www.ira.uka.de/~baas/pydoxy/
> I changed the doxygen config file with to INPUT_FILTER = "python
> pythfilter.py -f" and FILTER_SOURCE_FILES = YES.
>
> Now I get a complete different 'c::pure_doxygen Class Reference' (file
> try3) with no functions or variables described, but with a 'Inheritance
> diagram for c::pure_doxygen' (file classc_1_1pure_doxygen.png)!
> So this is different, but not really better.
>
> What do I wrong? Can I document the above example with doxygen at all?
> Could anybody explain me how?
>
> Thank you very much in advance!
>
> Thomas
>
> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
> <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
> <title>c::pure_doxygen Class Reference</title>
> <link href="doxygen.css" rel="stylesheet" type="text/css">
> </head><body>
> <!-- Generated by Doxygen 1.4.4 -->
> <div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="namespaces.html">Namespace List</a> | <a class="qindex" href="classes.html">Alphabetical List</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Class Members</a></div>
> <div class="nav">
> <a class="el" href="namespacec.html">c</a>::<a class="el" href="classc_1_1pure__doxygen.html">pure_doxygen</a></div>
> <h1>c::pure_doxygen Class Reference</h1><!-- doxytag: class="c::pure_doxygen" -->A class with doxygen remarks, only.
> <a href="#_details">More...</a>
> <p>
> <a href="classc_1_1pure__doxygen-members.html">List of all members.</a><table border="0" cellpadding="0" cellspacing="0">
> <tr><td></td></tr>
> <tr><td colspan="2"><br><h2>Public Member Functions</h2></td></tr>
> <tr><td class="memItemLeft" nowrap align="right" valign="top">def </td><td class="memItemRight" valign="bottom"><a class="el" href="classc_1_1pure__doxygen.html#c_1_1pure__doxygena0">foo1</a></td></tr>
>
> <tr><td class="mdescLeft"> </td><td class="mdescRight">The desc of var1 The foo1 method. <a href="#c_1_1pure__doxygena0"></a><br></td></tr>
> <tr><td colspan="2"><br><h2>Private Member Functions</h2></td></tr>
> <tr><td class="memItemLeft" nowrap align="right" valign="top">def </td><td class="memItemRight" valign="bottom"><a class="el" href="classc_1_1pure__doxygen.html#c_1_1pure__doxygend0">__init__</a></td></tr>
>
> <tr><td class="mdescLeft"> </td><td class="mdescRight">Constructor of <a class="el" href="classc_1_1pure__doxygen.html">pure_doxygen</a>. <a href="#c_1_1pure__doxygend0"></a><br></td></tr>
> </table>
> <hr><a name="_details"></a><h2>Detailed Description</h2>
> A class with doxygen remarks, only.
> <p>
>
> <p>
> Definition at line <a class="el" href="c_8py-source.html#l00008">8</a> of file <a class="el" href="c_8py-source.html">c.py</a>.<hr><h2>Member Function Documentation</h2>
> <a class="anchor" name="c_1_1pure__doxygend0"></a><!-- doxytag: member="c::pure_doxygen::__init__" ref="c_1_1pure__doxygend0" args="" --><p>
> <table class="mdTable" cellpadding="2" cellspacing="0">
> <tr>
> <td class="mdRow">
> <table cellpadding="0" cellspacing="0" border="0">
> <tr>
> <td class="md" nowrap valign="top">def c::pure_doxygen::__init__ </td>
> <td class="md" valign="top">( </td>
> <td class="mdname1" valign="top" nowrap> </td>
> <td class="md" valign="top"> ) </td>
> <td class="md" nowrap><code> [private]</code></td>
> </tr>
> </table>
> </td>
> </tr>
> </table>
> <table cellspacing="5" cellpadding="0" border="0">
> <tr>
> <td>
>
> </td>
> <td>
>
> <p>
> Constructor of <a class="el" href="classc_1_1pure__doxygen.html">pure_doxygen</a>.
> <p>
>
> <p>
> Definition at line <a class="el" href="c_8py-source.html#l00012">12</a> of file <a class="el" href="c_8py-source.html">c.py</a>. </td>
> </tr>
> </table>
> <a class="anchor" name="c_1_1pure__doxygena0"></a><!-- doxytag: member="c::pure_doxygen::foo1" ref="c_1_1pure__doxygena0" args="" --><p>
> <table class="mdTable" cellpadding="2" cellspacing="0">
> <tr>
> <td class="mdRow">
> <table cellpadding="0" cellspacing="0" border="0">
> <tr>
> <td class="md" nowrap valign="top">def c::pure_doxygen::foo1 </td>
> <td class="md" valign="top">( </td>
> <td class="md" nowrap valign="top"> </td>
> <td class="mdname" nowrap> <em>self</em>, </td>
> </tr>
> <tr>
> <td class="md" nowrap align="right"></td>
> <td class="md"></td>
> <td class="md" nowrap> </td>
> <td class="mdname" nowrap> <em>bar</em></td>
> </tr>
> <tr>
> <td class="md"></td>
> <td class="md">) </td>
> <td class="md" colspan="2"></td>
> </tr>
> </table>
> </td>
> </tr>
> </table>
> <table cellspacing="5" cellpadding="0" border="0">
> <tr>
> <td>
>
> </td>
> <td>
>
> <p>
> The desc of var1 The foo1 method.
> <p>
> <dl compact><dt><b>Parameters:</b></dt><dd>
> <table border="0" cellspacing="2" cellpadding="0">
> <tr><td valign="top"></td><td valign="top"><em>self</em> </td><td>The class itself </td></tr>
> <tr><td valign="top"></td><td valign="top"><em>bar</em> </td><td>An test parameter </td></tr>
> </table>
> </dl>
>
> <p>
> Definition at line <a class="el" href="c_8py-source.html#l00024">24</a> of file <a class="el" href="c_8py-source.html">c.py</a>. </td>
> </tr>
> </table>
> <hr>The documentation for this class was generated from the following file:<ul>
> <li><a class="el" href="c_8py-source.html">c.py</a></ul>
> <hr size="1"><address style="align: right;"><small>Generated on Thu Jul 28 12:25:11 2005 by
> <a href="http://www.doxygen.org/index.html">
> <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.4 </small></address>
> </body>
> </html>
> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
> <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
> <title>c::pure_python Class Reference</title>
> <link href="doxygen.css" rel="stylesheet" type="text/css">
> </head><body>
> <!-- Generated by Doxygen 1.4.4 -->
> <div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="namespaces.html">Namespace List</a> | <a class="qindex" href="classes.html">Alphabetical List</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Class Members</a></div>
> <div class="nav">
> <a class="el" href="namespacec.html">c</a>::<a class="el" href="classc_1_1pure__python.html">pure_python</a></div>
> <h1>c::pure_python Class Reference</h1><!-- doxytag: class="c::pure_python" --><a href="classc_1_1pure__python-members.html">List of all members.</a><table border="0" cellpadding="0" cellspacing="0">
> <tr><td></td></tr>
> <tr><td colspan="2"><br><h2>Public Member Functions</h2></td></tr>
> <tr><td class="memItemLeft" nowrap align="right" valign="top">def </td><td class="memItemRight" valign="bottom"><a class="el" href="classc_1_1pure__python.html#c_1_1pure__pythona0">foo2</a></td></tr>
>
> <tr><td colspan="2"><br><h2>Public Attributes</h2></td></tr>
> <tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classc_1_1pure__python.html#c_1_1pure__pythono0">var4</a></td></tr>
>
> <tr><td colspan="2"><br><h2>Private Member Functions</h2></td></tr>
> <tr><td class="memItemLeft" nowrap align="right" valign="top">def </td><td class="memItemRight" valign="bottom"><a class="el" href="classc_1_1pure__python.html#c_1_1pure__pythond0">__init__</a></td></tr>
>
> </table>
> <hr><a name="_details"></a><h2>Detailed Description</h2>
> <div class="fragment"><pre class="fragment">A class with python docs, only </pre></div>
> <p>
>
> <p>
> Definition at line <a class="el" href="c_8py-source.html#l00031">31</a> of file <a class="el" href="c_8py-source.html">c.py</a>.<hr><h2>Member Function Documentation</h2>
> <a class="anchor" name="c_1_1pure__pythond0"></a><!-- doxytag: member="c::pure_python::__init__" ref="c_1_1pure__pythond0" args="" --><p>
> <table class="mdTable" cellpadding="2" cellspacing="0">
> <tr>
> <td class="mdRow">
> <table cellpadding="0" cellspacing="0" border="0">
> <tr>
> <td class="md" nowrap valign="top">def c::pure_python::__init__ </td>
> <td class="md" valign="top">( </td>
> <td class="mdname1" valign="top" nowrap> </td>
> <td class="md" valign="top"> ) </td>
> <td class="md" nowrap><code> [private]</code></td>
> </tr>
> </table>
> </td>
> </tr>
> </table>
> <table cellspacing="5" cellpadding="0" border="0">
> <tr>
> <td>
>
> </td>
> <td>
>
> <p>
> <div class="fragment"><pre class="fragment">A class with python docs, only </pre></div>
> <p>
> Definition at line <a class="el" href="c_8py-source.html#l00035">35</a> of file <a class="el" href="c_8py-source.html">c.py</a>. </td>
> </tr>
> </table>
> <a class="anchor" name="c_1_1pure__pythona0"></a><!-- doxytag: member="c::pure_python::foo2" ref="c_1_1pure__pythona0" args="" --><p>
> <table class="mdTable" cellpadding="2" cellspacing="0">
> <tr>
> <td class="mdRow">
> <table cellpadding="0" cellspacing="0" border="0">
> <tr>
> <td class="md" nowrap valign="top">def c::pure_python::foo2 </td>
> <td class="md" valign="top">( </td>
> <td class="md" nowrap valign="top"> </td>
> <td class="mdname" nowrap> <em>self</em>, </td>
> </tr>
> <tr>
> <td class="md" nowrap align="right"></td>
> <td class="md"></td>
> <td class="md" nowrap> </td>
> <td class="mdname" nowrap> <em>bar</em></td>
> </tr>
> <tr>
> <td class="md"></td>
> <td class="md">) </td>
> <td class="md" colspan="2"></td>
> </tr>
> </table>
> </td>
> </tr>
> </table>
> <table cellspacing="5" cellpadding="0" border="0">
> <tr>
> <td>
>
> </td>
> <td>
>
> <p>
> <div class="fragment"><pre class="fragment">The foo2 method </pre></div>
> <p>
> Definition at line <a class="el" href="c_8py-source.html#l00040">40</a> of file <a class="el" href="c_8py-source.html">c.py</a>. </td>
> </tr>
> </table>
> <hr><h2>Member Data Documentation</h2>
> <a class="anchor" name="c_1_1pure__pythono0"></a><!-- doxytag: member="c::pure_python::var4" ref="c_1_1pure__pythono0" args="" --><p>
> <table class="mdTable" cellpadding="2" cellspacing="0">
> <tr>
> <td class="mdRow">
> <table cellpadding="0" cellspacing="0" border="0">
> <tr>
> <td class="md" nowrap valign="top"><a class="el" href="classc_1_1pure__python.html#c_1_1pure__pythono0">c::pure_python::var4</a> </td>
> </tr>
> </table>
> </td>
> </tr>
> </table>
> <table cellspacing="5" cellpadding="0" border="0">
> <tr>
> <td>
>
> </td>
> <td>
>
> <p>
> <div class="fragment"><pre class="fragment">Constructor of pure_python </pre></div>
> <p>
> Definition at line <a class="el" href="c_8py-source.html#l00038">38</a> of file <a class="el" href="c_8py-source.html">c.py</a>. </td>
> </tr>
> </table>
> <hr>The documentation for this class was generated from the following file:<ul>
> <li><a class="el" href="c_8py-source.html">c.py</a></ul>
> <hr size="1"><address style="align: right;"><small>Generated on Thu Jul 28 12:25:11 2005 by
> <a href="http://www.doxygen.org/index.html">
> <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.4 </small></address>
> </body>
> </html>
> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
> <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
> <title>c::pure_doxygen Class Reference</title>
> <link href="doxygen.css" rel="stylesheet" type="text/css">
> </head><body>
> <!-- Generated by Doxygen 1.4.4 -->
> <div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="namespaces.html">Namespace List</a> | <a class="qindex" href="hierarchy.html">Class Hierarchy</a> | <a class="qindex" href="classes.html">Alphabetical List</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="files.html">File List</a></div>
> <div class="nav">
> <a class="el" href="namespacec.html">c</a>::<a class="el" href="classc_1_1pure__doxygen.html">pure_doxygen</a></div>
> <h1>c::pure_doxygen Class Reference</h1><!-- doxytag: class="c::pure_doxygen" --><!-- doxytag: inherits="public" --><p>Inheritance diagram for c::pure_doxygen:
> <p><center><img src="classc_1_1pure__doxygen.png" usemap="#c::pure_doxygen_map" border="0" alt=""></center>
> <map name="c::pure_doxygen_map">
> <area href="classpublic.html" alt="public" shape="rect" coords="0,0,106,24">
> </map>
> <table border="0" cellpadding="0" cellspacing="0">
> <tr><td></td></tr>
> </table>
> <hr><a name="_details"></a><h2>Detailed Description</h2>
>
> <p>
>
> <p>
> Definition at line <a class="el" href="c_8py-source.html#l00013">13</a> of file <a class="el" href="c_8py-source.html">c.py</a>.<hr>The documentation for this class was generated from the following file:<ul>
> <li><a class="el" href="c_8py-source.html">c.py</a></ul>
> <hr size="1"><address style="align: right;"><small>Generated on Thu Jul 28 13:11:28 2005 by
> <a href="http://www.doxygen.org/index.html">
> <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.4 </small></address>
> </body>
> </html>
|
