docstrings, invention there of

[Barry A. Warsaw]

>>>>> "TP" == Tim Peters <tim.one at home.com> writes:

    TP> Guido wouldn't claim that docstrings were original with
    TP> Python.  I'm not sure who "we" refers to here, or to what "the
    TP> interpreter"; Python's docstrings were most directly inspired
    TP> by the similar facility in Emacs's elisp interpreter (and it
    TP> wasn't original there either, of course -- the idea of
    TP> attaching doc properties to Lisp atoms and extracting them via
    TP> introspection must go back several decades).

Tim's got the lineage correct here.

At the first Python workshop at NIST in 1994, the subject of
docstrings came up.  Emacs Lisp was the example model pointed to most
often, not surprisingly because the percentage of Emacsheads in
attendance was quite high. :)

We couldn't agree on the structure of the strings, except for two
things, both taken from our experience with Emacs Lisp: they should be
the very first thing in the block (except perhaps for comments), and
that the first line should be a complete, and short sentence.

-Barry