On Friday 02 September 2005 08:28 am, Michael Ekstrand wrote: > On Thu, 1 Sep 2005 22:38:03 -0500 > Terry Hancock <[EMAIL PROTECTED]> 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 -- http://mail.python.org/mailman/listinfo/python-list
