=====================
 Docstring Semantics
=====================
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Revision: $Revision$
:Date: $Date$

These are notes for a possible future PEP providing the final piece of
the Python docstring puzzle.

PythonDoc
=========

A Python version of the JavaDoc semantics (not syntax).  A set of
conventions which are understood by the Docutils.

- Can we extract comments from parsed modules?  Could be handy for
  documenting function/method parameters::

      def method(self,
                 source,        # path of input file
                 dest           # path of output file
                ):

  This would save having to repeat parameter names in the docstring.

  Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG]
  Documentation tool":

      it would be quite hard to add a new param to this method without
      realising you should document it

- Use field lists or definition lists for "tagged blocks".

- Frederic Giacometti's "iPhrase Python documentation conventions" is
  an attachment to his Doc-SIG post of 2001-05-30
  (http://mail.python.org/pipermail/doc-sig/2001-May/001840.html).


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: