Docstring Semantics -- notes initially

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@12 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 38 insertions, 0 deletions

diff --git a/docutils/docs/dev/semantics.txt b/docutils/docs/dev/semantics.txt
new file mode 100644
index 000000000..96d2d5644
--- /dev/null
+++ b/docutils/docs/dev/semantics.txt
@@ -0,0 +1,38 @@
+=====================
+ 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).