[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 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.


    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

    Other than that, I think this section is an excellent summary.


    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).

.. [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 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

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...

.. [2]: see pep257example.txt
.. _reST: obviously, reStructuredText.

PEP 258 (DPS generic implementation details)
version 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

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

    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

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.)