[Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code
Fred L. Drake, Jr.
fdrake at acm.org
Thu May 19 15:42:15 CEST 2005
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>
More information about the Doc-SIG
mailing list