Re: [Numpy-discussion] Tests and code documentation

[Charles R H. <cha...@gm...>]

Hi,

On 9/21/06, Robert Kern <rob...@gm...> wrote:
>
> Steve Lianoglou wrote:
> > So .. I guess I'm wondering why we want to break from the standard?
>
> We don't as far as Python code goes. The code that Chuck added
> Doxygen-style
> comments to was C code. I presume he was simply answering Sebastian's
> question
> rather than suggesting we use Doxygen for Python code, too.


Exactly. I also don't think the Python hack description applies to doxygen
any longer. As to the oddness of \param or @param, here is an example from
Epydoc using Epytext

    @type  m: number
    @param m: The slope of the line.
    @type  b: number
    @param b: The y intercept of the line.  The X{y intercept} of a

Looks like they borrowed something there ;) The main advantage of epydoc vs
doxygen seems to be that you can use the markup inside the normal python
docstring without having to make a separate comment block. Or would that be
a disadvantage? Then again, I've been thinking of moving the python function
docstrings into the add_newdocs.py file so everything is together in one
spot and that would separate the Python docstrings from the functions
anyway.

I'll fool around with doxygen a bit and see what it does. The C code is the
code that most needs documentation in any case.

Chuck