docs/dev/semantics.txt

   1 =====================
   2  Docstring Semantics
   3 =====================
   4 :Author: David Goodger
   5 :Contact: docutils-develop@lists.sourceforge.net
   6 :Revision: $Revision$
   7 :Date: $Date$
   8 :Copyright: This document has been placed in the public domain.
   9
  10 These are notes for a possible future PEP providing the final piece of
  11 the Python docstring puzzle: docstring semantics or documentation
  12 methodology.  `PEP 257`_, Docstring Conventions, sketches out some
  13 guidelines, but does not get into methodology details.
  14
  15 I haven't explored documentation methodology more because, in my
  16 opinion, it is a completely separate issue from syntax, and it's even
  17 more controversial than syntax.  Nobody wants to be told how to lay
  18 out their documentation, a la JavaDoc_.  I think the JavaDoc way is
  19 butt-ugly, but it *is* an established standard for the Java world.
  20 Any standard documentation methodology has to be formal enough to be
  21 useful but remain light enough to be usable.  If the methodology is
  22 too strict, too heavy, or too ugly, many/most will not want to use it.
  23
  24 I think a standard methodology could benefit the Python community, but
  25 it would be a hard sell.  A PEP would be the place to start.  For most
  26 human-readable documentation needs, the free-form text approach is
  27 adequate.  We'd only need a formal methodology if we want to extract
  28 the parameters into a data dictionary, index, or summary of some kind.
  29
  30
  31 PythonDoc
  32 =========
  33
  34 (Not to be confused with Daniel Larsson's pythondoc_ project.)
  35
  36 A Python version of the JavaDoc_ semantics (not syntax).  A set of
  37 conventions which are understood by the Docutils.  What JavaDoc has
  38 done is to establish a syntax that enables a certain documentation
  39 methodology, or standard *semantics*.  JavaDoc is not just syntax; it
  40 prescribes a methodology.
  41
  42 - Use field lists or definition lists for "tagged blocks".  By this I
  43   mean that field lists can be used similarly to JavaDoc's ``@tag``
  44   syntax.  That's actually one of the motivators behind field lists.
  45   For example, we could have::
  46
  47       """
  48       :Parameters:
  49           - `lines`: a list of one-line strings without newlines.
  50           - `until_blank`: Stop collecting at the first blank line if
  51             true (1).
  52           - `strip_indent`: Strip common leading indent if true (1,
  53             default).
  54
  55       :Return:
  56           - a list of indented lines with mininum indent removed;
  57           - the amount of the indent;
  58           - whether or not the block finished with a blank line or at
  59             the end of `lines`.
  60       """
  61
  62   This is taken straight out of docutils/statemachine.py, in which I
  63   experimented with a simple documentation methodology.  Another
  64   variation I've thought of exploits the Grouch_-compatible
  65   "classifier" element of definition lists.  For example::
  66
  67       :Parameters:
  68           `lines` : [string]
  69               List of one-line strings without newlines.
  70           `until_blank` : boolean
  71               Stop collecting at the first blank line if true (1).
  72           `strip_indent` : boolean
  73               Strip common leading indent if true (1, default).
  74
  75 - Field lists could even be used in a one-to-one correspondence with
  76   JavaDoc ``@tags``, although I doubt if I'd recommend it.  Several
  77   ports of JavaDoc's ``@tag`` methodology exist in Python, most
  78   recently Ed Loper's "epydoc_".
  79
  80
  81 Other Ideas
  82 ===========
  83
  84 - Can we extract comments from parsed modules?  Could be handy for
  85   documenting function/method parameters::
  86
  87       def method(self,
  88                  source,        # path of input file
  89                  dest           # path of output file
  90                 ):
  91
  92   This would save having to repeat parameter names in the docstring.
  93
  94   Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG]
  95   Documentation tool":
  96
  97       it would be quite hard to add a new param to this method without
  98       realising you should document it
  99
 100 - Frederic Giacometti's `iPhrase Python documentation conventions`_ is
 101   an attachment to his Doc-SIG post of 2001-05-30.
 102
 103
 104 .. _PEP 257: http://www.python.org/peps/pep-0257.html
 105 .. _JavaDoc: http://java.sun.com/j2se/javadoc/
 106 .. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/
 107 .. _Grouch: http://www.mems-exchange.org/software/grouch/
 108 .. _epydoc: http://epydoc.sf.net/
 109 .. _iPhrase Python documentation conventions:
 110    http://mail.python.org/pipermail/doc-sig/2001-May/001840.html
 111
 112 \f
 113 ..
 114    Local Variables:
 115    mode: indented-text
 116    indent-tabs-mode: nil
 117    sentence-end-double-space: t
 118    fill-column: 70
 119    End: