[Doc-SIG] Documentation tool

[Robin Friedrich]

----------
> From: Jim Fulton <jim.fulton@Digicool.com>
> > Mark Hammond---
> > class Foo:
> >   """Docstring describing verbosely what the class is for."""
> >   def __init__(self,
> >                        parent, # @parm <o Window>|The parent window
> >                        style,    # @parm int|Window style.  This
> > *must* not be 0
> >                        )
> >          #@ comm Only call this function when the sun is shining.
> > Otherwise
> >          # an assetion will be raised.
> >          assert SunShining(), "Sun not shining"
> >          self.SomeFunc() # @see SomeFunc
> >          return a,b,c # @rdesc The result is a tuple of a,b,c,
> > unless the moon is full.
> > 
> > Now, this obviously contrived example appeals much more to me than
> > attempting to write it up correctly in the docstring.  Even though
> > the docstring is close to the code, it is not close enough.  Having
> > it _in_ the code makes for more reliable updating (eg, it would be
> > quite hard to add a new param to this method without realising you
> > should document it.)
> 
> I agree that it would be nice to document the arguments directly.
> I think it would also be handy to have this information at run 
> time, so I'd prefer to go farther than a commenting convention.
> Perhaps some sort of argument doc strings could be supported.
> Perhaps this could be folded into some syntax for optional
> argument typing.

I vaguely remember this discussed last year. This implies changes to the
language; but requiring everyone to use a newer version (~1.6) seems weak.
(Original requirements, admittedly only drafted by me, stipulated 1.5
compatibility.) I would agree that it would be good to have this
information at runtime. But without a change to the language we are back to
the doc-string again.
>  
> > The other benefit is that the generated documentation looks more
> > professional.  _Every_ method is documented with identical header
> > ordering and grouping, etc.  No need to put stuff in some order that
> > you can never remember.

The pythondoc approach is to populate a DOM with info gathered "by some
means" and then pass that structure to a thing that renders it in a user
specified manner. Order is no longer the important factor. We could just as
well plug in some auxiliary source parsing to pick up argument attributes
and populate the DOM as Daniel mentioned. Thus autoduck can have a nest;-)

I hate to rehash this but this brings up the age old debate over parsing
vs. import/introspection. The intent is to support both Python source and C
extension code. What are the scenarios for usage guys? How much info is
gathered via import vs gathered via a parser?