[Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code

[Fred L. Drake, Jr.]

On Monday 02 May 2005 23:04, David Goodger wrote:
 > [Felix Wiemann]
 > > Maybe add a special token to the docstring that the method shouldn't
 > > appear in auto-documentation?
 >
 > A special comment perhaps?  Or a function attribute?  I don't think
 > such metadata should be put in the docstring; that's for
 > documentation.

I'd be reasonably happy with the special comment approach, if we generate 
documentation by parsing.  The more dynamic things become in Python, the less 
convinced I am that parsing alone is actually a workable approach.  It might 
be easier to use special comments if the compiler understood them to set 
attributes on the objects marked.

More realistically, we could very easily use decorators with Python 2.4 and 
newer.  Unless someone has time to work on this, that's probably good enough.  
It might not be hard to adjust epydoc to use annotations added that way.

For example::

    @docinfo(hidden=True)
    def my_really_magical_function(*args, **kw):
        pass

Something like this could also be used to indicate grouping::

    @docinfo(group='Magical Things')
    def my_public_magical_function(*args, **kw):
        pass

 > OTOH, the common convention for "weakly private" or "internal" can be
 > used: a single underscore prefix.  E.g.:

I think this is a really weak convention.  It might be helpful for eliminating 
non-public things, but it's not unusual for APIs intended for subclasses to 
include the single underscore prefix.  We'd definately want some way to 
denote these categorizations explicitly.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>