Epydoc - Documenting class members?

[Terry Hancock]

On Friday 02 September 2005 08:28 am, Michael Ekstrand wrote:
> On Thu, 1 Sep 2005 22:38:03 -0500
> Terry Hancock <hancock at anansispaceworks.com> wrote:
> > > I don't like this, I want to document where I declare the variable
> > > below. Doxygen (www.doxygen.org), for one example, knows how to do
> > > this.
> > 
> > Then use Doxygen if it's a superior product. I presume
> > it knows how to handle Python code, then?
> 
> Doxygen does not support Python - it only works for C-like languages
> (C, Java, PHP). Hence the need/desire for something (e.g. extension to
> epydoc) that does this.

Yeah, I suspected that. I was being sarcastic, there.

It's very annoying to answer someone's question
exactly and be told "I don't like that" like it's
even up for discussion.

That's like saying French is wrong because it uses
"double negatives" or puts adjectives after nouns
instead of before.

I mean, if you want to be understood in French,
you're just going to have to speak French.  Or,
just don't speak French, and live with the consequences
of that.  The point is, it's your choice -- if you
don't like it, don't use it. Write something you
like better.

Personally, I would consider that a massive waste
of time.  But then again, I learned to live with
"n'est pas rien", too, instead, for example, trying
to convince all the residents of France to adopt
English grammar.

Perhaps, more to the point, I didn't write epydoc,
so I'm not in much of a position to comment about
the wisdom of its design.

I *can* say that Python does not itself provide any
way to attach a docstring to a class or instance
attribute -- so the nearest docstring really is the
one for the class.  Given that epydoc, like pydoc
only uses introspection to collect documentation, it
has no means to capture the comments the OP wanted
to catch.

That was one strength of happydoc, but AFAICT, it
didn't provide *any* means to document class or
instance attributes, which I considered a real drawback,
since I like to use attribute/property interfaces in
Python, now that it's possible to do so.  I have
always thought get/set methods were a bit of a 
hare-brained idea, so it's nice to have alternatives.

The thing that turned me off of happydoc, though, was
not that, but what is surely a bug -- the mechanism
for generating HTML documentation sets depended on the
*absolute* location of the source tree being documented.

So, for example, if you unpacked it in your home
directory, it would use something like
 ./home/yourname/pkgname/doc/lib as the prefix.  Which
is obviously a problem -- especially if the source tree
will be maintained by more than one person.  I think
this problem was solved in version 3.x, but there was
never a full release of happydoc 3.x, so it's not
very convenient to use.

Epydoc produces very nice documentation, though, so I'm
happy with the switch. I found an easy way to integrate
my authored documentation along with the automated
API documentation, which I think is a terrific "best of
both worlds" solution.  I'm still experimenting, but I
really like the idea of being able to produce well-documented
code with so little effort.

But then, I'm just an enthusiastic amateur.

Cheers,
Terry

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com