[Doc-SIG] Comments on the DPS texts
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Fri, 3 Aug 2001 11:01:36 +0100
############
DPS comments
############
Hmm - let's see if *I* can write in reST, without too much reference to
the documents (memo to self: prepare cheat sheet).
PEP 256 (DPS framework) version 1.1.1.2 of 2001/07/19
=====================================================
.. namespace:: 256 is pep-0256.txt [1]_
.. namespace:: 257 is pep-0257.txt
256:`Abstract`_[1]_, paragraph 1:
You don't explicitly mention methods. Whilst a method *is*,
technically, a function, I think it *would* be better to include
them here as well (as, for instance, is done in the first paragraph
of 257:`What is a Doscstring?`_).
In the same paragraph, in the second sentence, you say:
inside the definition
which I think would read better as, for instance:
inside their definition
(but this one is *very* much a matter of style).
256:`Abstract`_, paragraph 2, last sentence:
You say "The issues surrounding docstring procesing have been
contentious and difficult to solve". Indeed.
256:`Rationale`_
I think that you should add Edward Loper to the list of previous
attempts at writing systems. His approach of rigorous definition,
and dissection of differences between systems, is to my mind quite
important.
Other than that, I think this section is an excellent summary.
256:`Specification`_
The diagram at the end of this is indeed much too wide, and really
needs redrawing, preferably as an image (even though PEPs don't
currently support that).
Footnotes
---------
.. [1] Hmm - it is useful in a document like this to be able to refer to
targets in another document. I've "invented" the `namespace` directive
for this purpose, but I don't pretend to like it, nor do I particularly
think that I've got the syntax for *using* a namespace correct. Regard
it as a naff convention for these documents only...
Miscellaneous notes
-------------------
We should explicitly allow control-L (formfeed) in documents. It is
*very* useful in navigating around documents which are in plain text,
especially in the Emacs family of editors.
PEP 257 (Docstring conventions) version 1.2.1.1 of 2001/07/19
=============================================================
.. namespace:: 257 is pep-0257
.. comment:: yes, I know that's a duplicate declaration - I assume that
that is allowed and will work? (i.e., have no effect if the same, and
override if different).
257:`What is a Docstring?`_
The first paragraph of this, first sentence, gets the list of places
a docstring can occur correct - apply elsewhere as appropriate.
In the second paragraph after the little two item list, you describe
"""..""" and r"""..""" strings, but not the Unicode variants
thereof. I think they should be explicitly mentioned, as how one
gets Unicode into docstrings, or else as not being allowed (for the
moment) for docstrings (surely that last is not the situation).
257:`One-line Docstrings`_
Hmm. When discussing the "signature" in C functions - shouldn't the
DPS mandate that this signature line should be (a) of a particular
format [the obvious one!], and (b) that the tool "looking for" and
interpreting code structure should make use of said signature if
present.
257:`Multi-line Docstrings`_
Guido's example as presented::
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
is not valid reST_. Whilst that's not entirely unreasonable (since
the DPS is not tied to reST), it would, I think, be consistent if
it were recast as such. However, trying to do that has some
interesting implications, so I'll address it separately [2]_.
257:`Multi-line Docstrings`_
At the end you say: "This way, Emacs' fill-paragraph command can be
used on it."
Is this a problem in modern [X]Emacs? <fx: typing of simple example
Python script> - ah, I see it still is.
Since presumably we will ultimately be wanting to have an reST mode
for [X]Emacs, as a subsidiary mode within Python mode (or however
one describes it), I think that this requirement should be removed.
Miscellaneous notes
-------------------
OK, I remembered why I sometimes want non-breaking spaces. In contexts
such as ``PEP 258``, it does not make sense (in the presented text) to
split the line between the two "words". This is important for things
like ``ISO/IEC 8211`` as well - normal presentation standards require
one *not* to split between the two parts.
I can see that people may say "so what, put up with it", but since a lot
of my coding has *been* with reference to standards, getting this wrong
in the presented documentation is *not* something I want to do - it make
me look dumb, as if I did not know what I was doing, not something I
favour (!).
On the other hand, how to get round it? Maybe we just need to allow an
escaped space to be a non-breaking space - since I lost the backslash
battle, I might as well lose it thoroughly. In which case my examples
would be written "PEP\ 258" and "ISO/IEC\ 8211".
Now, personally I think that reads horribly in the plain text, but if my
aim is actually to produce *documentation* from docstrings, it may be
just good enough...
References
----------
.. [2]: see pep257example.txt
.. _reST: obviously, reStructuredText.
PEP 258 (DPS generic implementation details)
version 1.1.1.3 of 2001/07/19
============================================
.. comment:: OK, so I've found an instance of a multi-line header...
.. namespace:: 257 is pep-0257
.. namespace:: 258 is pep-0258.txt
258:`Docstring extraction rules`_ item 2.a
The same comment applies as in other places about mentioning methods
as well as functions. See 257:`What is a Docstring?`_, first
paragraph.
258:`Docstring extraction rules`_ item 3
At the end of the first paragraph, you say "Of course, standard
Python parsing tools such as the 'parser' library module should be
used.".
I think that is too strong a statement - it should either say "may
be used" or it should say something more like "are likely to be used
in general".
258:`Attribute docstrings`_ item 1
Does this really mean to leave functions out? That is, can one
really not do::
def fred():
a = 1
"""``a`` is a silly name for a value."""
This seems a bit of a limitation to me - admittedly I don't have PEP
224 (or any of the commentary on it) to hand here.
258:`Additional docstrings`_
When you say "this breaks 'from __future__ import'" can you give
more context (you don't refer to a PEP, and also I don't off hand
remember how __future__ imports work in detail, so an explanation
*at hand* would be a very good thing).
If it means what I think it means (that the __future__ statement
must be the first statement in a module, excepting a docstring (and
presumably another __future__!)), it would seem that option 2 is the
obvious one to adopt.
If there *are* going to be additional docstrings, can I ask that we
have some way of *identifying* them - consider a (future usage) of
a parser (using a docstring to store parse rules) within something
like Zope (where a docstring is/was used to provide other
information) -- here one might notionall have three docstrings, and
still claim not to be insane. Identifying them in some way would
seem absolutely necessary...
For instance::
def information_overload(fred):
"""A simple function with too much metadata.
fred -- the only argument, should be Fred's surname
"""
""".. zope::
<zope info goes here>
"""
""".. yapps::
<parser definitions go here>
"""
(OK, maybe it's a bit cheeky leveraging off directives.)
258:`Choice of Docstring format`_
This sounds sensible to me. I had thought over the implications of
allowing the user to specify different formats at different places
in a module (and even at different "levels" - e.g., within a class),
but it's clearly not worth the hassle, and unlikely to be useful.
The default of "plaintext" seems sensible - indeed, it's not clear
to me that one need change it *ever*, since plain text is always a
valid form of documentation.
I suggest format names are something like:
- "plaintext" (the default)
- "reST" (reStructuredText)
- "ST" (StructuredText - for Zope compatibility,
and thus maybe deprecated)
- "STNG" (StructuredTextNG - ditto)
Other names
OK, so the DPS is responsible (in some sense) for the __docformat__
name. Should it also be aware of some of the other (semi) standard
names that people use - the following are ones I'm aware of:
* __author__
* __version__
* __history__ (this is less common)
* __copyright__ (I've just made this one up)
Whilst these are in the Python, rather than in the docstrings, they
clearly *are* part of the documentation, and are clearly things that
the user will want a documentation presentation tool to show to
them.
258:`Intermediate data structure`_
It should be made clear(er) that the DOM tree is intermediate
between the input parser and the output formatter - it is not a
requirement for the *internal* workings of either. The first
sentence of this section reads as if it means that the input parser
*must* use the DOM tree inside itself.
258:`Output management`_
The final sentence: "Use a directory hierarchy ... couldn't run on
MacOS)" doesn't make sense to me - please explain it.
258:`Error handling`_
Good. Of course, these correspond to the VMS information, warning,
error and fatal message levels (and those might be good names to use
for them).
--
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)