[Doc-SIG] epydoc 1.1 release

[Edward Loper]

M.-A. Lemburg wrote:
> Edward Loper wrote:
> 
>> - Some advantages of pydoc are:
 >>     [...]
> 
> I like the output of epydoc a lot (except maybe for the dim
> colors ;-). Wouldn't it be possible to add most of the above
> in form of options to epydoc ?

For some of these, they would be added (as defaults, not options) if I 
had time to code them.  And there's plenty more on the epydoc todo list 
(see the comment at the bottom of epydoc.py/__init__.py).

Others don't really go with epydoc's design philosophy.  In particular, 
I doubt epydoc will ever automatically (implicitly) create intra-doc 
links.  This can sometimes make mistakes, and puts links all over the 
place.  I would rather have the user explicitly create links.  I'm also 
unlikely to add support for processing python comments.  And I doubt 
I'll add manpage-style and interpreter (pydoc.help) usage, because pydoc 
already does such a good job at it, and is already part of the standard 
library.

> What I don't understand about epydoc is why it uses a syntax
> that's almost JavaDoc-style, but not all the way ?

Actually, the only real similarity between epytext and javadoc comments 
is that the @field's look roughly similar.  E.g., note that you have to 
use explicit <p>'s in javadoc to mark paragraph boundaries; and you have 
to explicitly use <ul><li></ul> for lists, etc.

I find javadoc's markup conceptually ugly.  The idea of allowing 
unrestricted html code in your docstring really bothers me.  And it 
makes the docstrings very difficult to read when you're looking at the 
source code.  That said, it might be good to add support for 
javadoc-style docstrings, just because it would reduce the learning 
curve for java programmers.  It wouldn't be that technically difficult 
to do; javadoc docstrings are basically just raw html plus @field's. 
And epydoc's docstring processing is pretty compartmentalized.  But I 
only have limited time to spend on epydoc, and that's not a feature that 
I feel very motivated to add.

If someone else wants to add it, I'd certainly accept a patch.  What 
would probably be involved is:

   - Write epydoc/javadoc.html to parse javadoc-style comments.  It
     would probably produce an xml document with a <javadoc> node
     that contains a <rawhtml> node followed by a <fieldlist> node
     similar to epytext's.  Of course, if you wanted to handle
     javadoc's syntax for intradocumentation links, etc, you would
     need to do a little more work.
   - Patch ObjDoc.__parse_docstring in epydoc/objdoc.py to recognize
     'javadoc' as a value for __docformat__.
   - Patch HTML_Formatter._dom_to_html_helper in epydoc/html.py to
     handle <rawhtml> elements.
   - (Optionally) add all of the field's that javadoc implements that
     epydoc does not (e.g., @since and @depreciated).

Then you could just use "--docformat javadoc" to set the default 
docstring format to javadoc, or add "__docformat__='javadoc'" to each 
module that uses javadoc-style docstrings.

> Think of it this way: Java programmers are usually very aware
> of JavaDoc style comments, so switching to epydoc for Python
> programming would probably cause them more trouble due to the
> subtle differences than someone who has never worked in this
> context before.

I agree that this would reduce the learning curve for java programmers. 
  And it might help make things more consistant for API docs of jython 
programs.  But as I said, I think that javadoc comments are ugly. :)

-Edward