On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote: >Overall, I think that we can make stdlib docstrings valid reST -- even >if it's reST without much markup -- but valid, so that people pulling >in stdlib doc- strings into Sphinx docs won't get ugly warnings. > >What I would *not* like to see is heavy markup and Sphinx specifics -- >that would only make sense if we included the docstrings in the docs, >and I don't see that coming.
Does it make sense to add (reST-style) epydoc markup for API signatures?
E.g.
def create_foo(name, parent=None):
"""Create the named foo.
The named foo must not already exist, but if optional `parent` is given,
it must exist.
:param name: The name of the new foo.
:type name: string
:param parent: The new foo's parent. If given, this must exist.
:type parent: string
:return: The new foo.
:rtype: `Foo`
:raises BadFooNameError: when `name` is illegal.
:raises FooAlreadyExistsError: when a foo with `name` already exists.
:raises BadParentError: when the foo's parent does not exist.
"""
We could then generate automatic API docs from this, a la:
http://www.blender.org/documentation/248PythonDoc/
-Barry
signature.asc
Description: PGP signature
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
