Am 07.07.2010 20:12, schrieb Barry Warsaw: > 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/
Yes, but: do we want this? Georg _______________________________________________ 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