From ae4f07d30c23b941eb03e5ad59fb6600e74012a2 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 13 Apr 2002 17:18:52 +0000 Subject: Docstring Semantics -- notes initially git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@12 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/semantics.txt | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/dev/semantics.txt (limited to 'docs/dev/semantics.txt') diff --git a/docs/dev/semantics.txt b/docs/dev/semantics.txt new file mode 100644 index 000000000..96d2d5644 --- /dev/null +++ b/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). -- cgit v1.2.1 From 4be9c5e656e39a59bf1fb4f664a2ab157e5ddb71 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 20 Apr 2002 03:17:12 +0000 Subject: emacs stanza git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@23 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/semantics.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/dev/semantics.txt') diff --git a/docs/dev/semantics.txt b/docs/dev/semantics.txt index 96d2d5644..f6ec09ebd 100644 --- a/docs/dev/semantics.txt +++ b/docs/dev/semantics.txt @@ -36,3 +36,12 @@ conventions which are understood by the Docutils. - 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: -- cgit v1.2.1 From a3bc9fff9ecee87efe0f053530371b7a408d86a0 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 2 Oct 2002 03:25:25 +0000 Subject: Updated with text from a Doc-SIG response to Dallas Mahrt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@750 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/semantics.txt | 85 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 78 insertions(+), 7 deletions(-) (limited to 'docs/dev/semantics.txt') diff --git a/docs/dev/semantics.txt b/docs/dev/semantics.txt index f6ec09ebd..e42c9ea01 100644 --- a/docs/dev/semantics.txt +++ b/docs/dev/semantics.txt @@ -7,13 +7,78 @@ :Date: $Date$ These are notes for a possible future PEP providing the final piece of -the Python docstring puzzle. +the Python docstring puzzle: docstring semantics or documentation +methodology. `PEP 257`_, Docstring Conventions, sketches out some +guidelines, but does not get into methodology details. + +I haven't explored documentation methodology more because, in my +opinion, it is a completely separate issue from syntax, and it's even +more controversial than syntax. Nobody wants to be told how to lay +out their documentation, a la JavaDoc_. I think the JavaDoc way is +butt-ugly, but it *is* an established standard for the Java world. +Any standard documentation methodology has to be formal enough to be +useful but remain light enough to be usable. If the methodology is +too strict, too heavy, or too ugly, many/most will not want to use it. + +I think a standard methodology could benefit the Python community, but +it would be a hard sell. A PEP would be the place to start. For most +human-readable documentation needs, the free-form text approach is +adequate. We'd only need a formal methodology if we want to extract +the parameters into a data dictionary, index, or summary of some kind. + PythonDoc ========= -A Python version of the JavaDoc semantics (not syntax). A set of -conventions which are understood by the Docutils. +(Not to be confused with Daniel Larsson's pythondoc_ project.) + +A Python version of the JavaDoc_ semantics (not syntax). A set of +conventions which are understood by the Docutils. What JavaDoc has +done is to establish a syntax that enables a certain documentation +methodology, or standard *semantics*. JavaDoc is not just syntax; it +prescribes a methodology. + +- Use field lists or definition lists for "tagged blocks". By this I + mean that field lists can be used similarly to JavaDoc's ``@tag`` + syntax. That's actually one of the motivators behind field lists. + For example, we could have:: + + """ + :Parameters: + - `lines`: a list of one-line strings without newlines. + - `until_blank`: Stop collecting at the first blank line if + true (1). + - `strip_indent`: Strip common leading indent if true (1, + default). + + :Return: + - a list of indented lines with mininum indent removed; + - the amount of the indent; + - whether or not the block finished with a blank line or at + the end of `lines`. + """ + + This is taken straight out of docutils/statemachine.py, in which I + experimented with a simple documentation methodology. Another + variation I've thought of exploits the Grouch_-compatible + "classifier" element of definition lists. For example:: + + :Parameters: + `lines` : [string] + List of one-line strings without newlines. + `until_blank` : boolean + Stop collecting at the first blank line if true (1). + `strip_indent` : boolean + Strip common leading indent if true (1, default). + +- Field lists could even be used in a one-to-one correspondence with + JavaDoc ``@tags``, although I doubt if I'd recommend it. Several + ports of JavaDoc's ``@tag`` methodology exist in Python, most + recently Ed Loper's "epydoc_". + + +Other Ideas +=========== - Can we extract comments from parsed modules? Could be handy for documenting function/method parameters:: @@ -31,11 +96,17 @@ conventions which are understood by the Docutils. 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. + -- 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). +.. _PEP 257: http://www.python.org/peps/pep-0257.html +.. _JavaDoc: http://java.sun.com/j2se/javadoc/ +.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ +.. _Grouch: http://www.mems-exchange.org/software/grouch/ +.. _epydoc: http://epydoc.sf.net/ +.. _iPhrase Python documentation conventions: + http://mail.python.org/pipermail/doc-sig/2001-May/001840.html .. -- cgit v1.2.1 From 4cc798623cc64d7cd12d72105edb830ac7af07e6 Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 9 Jun 2003 21:26:31 +0000 Subject: clarification of public domain status git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1409 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/semantics.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/dev/semantics.txt') diff --git a/docs/dev/semantics.txt b/docs/dev/semantics.txt index e42c9ea01..cd20e15f6 100644 --- a/docs/dev/semantics.txt +++ b/docs/dev/semantics.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. These are notes for a possible future PEP providing the final piece of the Python docstring puzzle: docstring semantics or documentation -- cgit v1.2.1