[Grok-dev] How complete should docstrings be?

[Brandon Craig Rhodes]

So I have started writing a docstring for `grok.View`, and started
explaining in it how `grok.View` works, and if I carry through with this
project, then it will wind up being several paragraphs long.  It will be
a complete little summary of how a `grok.View` behaves: it will list
*every* directive that can be used with a `grok.View`, and list *every*
default of each of those directives.

Why do I want to put all this information in a docstring?

Because I believe that when someone is using an IDE (or just looks
something up in the source code themselves), and is either writing or
debugging a `grok.View` that is not behaving as they expect, their
natural inclination is to hit the "What is this?" button and read the
`grok.View` docstring.  This leads me to formulate some "Dogmas of Grok
Docstrings" that I wanted to ask the mailing list about before
continuing my work:

 1. Class docstrings have different audiences, depending on the class.
    A class "internal" to Grok, that users do not subclass from or use
    directly, has the DEVELOPER as its audience.  A class "advertised"
    by Grok (or a Grok directive), that users will be calling or
    subclassing from or instantiating, has Grok USERS as its audience.
    (Yes, Grok "users" are also "developers" of their own Grok-based
    application, but I have to use a different word for them!)

 2. When a docstring has the DEVELOPER as its audience, it can be brief,
    saying a few words about why a class is present, and maybe a brief
    note about how it relates to other classes or interfaces or the
    Component Architecture.  Developers are expected to hunt around and
    see how things connect, so they mostly need a docstring to explain
    what a class is for.

 3. When a docstring has the USER as its audience, however, it should be
    exhaustive.  The user looking at the `grok.View` docstring should
    receive complete, but of course very terse, instructions about every
    Grok directive that can be used with the class, and what default
    Grok will use if the directive is absent.  This makes the docstring
    a truly useful reference to appear when the developer is using a
    `grok.View`, is confused by its behavior, and either looks up the
    class in the source code or asks for the docstring in his IDE.

 4. The first consequence of Dogma #3 is that docstrings on Grok base
    classes and on Grok directives will, together, form a fairly
    complete Grok reference.  In fact, I think that these docstrings
    should be automatically collected together to form the Grok
    Reference, and that we should not keep separate copies of these
    descriptions; the docstrings should form the "online version" of the
    Grok reference.  When writing these docstrings, I should start with
    a cut-and-paste of the material already in the existing Reference
    (well, for the classes that already documented there).

 5. The second consequence of Dogma #3 is that we will have repetition
    between docstrings.  For example, the information that the directive
    `grok.name()` is used to name a `grok.View`, and that the default
    value is derived from the class name, would appear *both* in the
    docstring of `grok.name()` *and* in the docstring of `grok.View`.

 6. Finally, I believe that current IDEs (and other code-browsing
    software) are not good at cross-referencing things mentioned in
    docstrings.  If things were different, we might be tempted to cut
    down on the repetition asserted by Dogma #5: instead of saying some
    of the same things in `grok.name()` as we say in `grok.View()`, we
    might just mention in the `grok.name()` docstring that "this
    directive can be used with the following classes: `grok.View`", and
    then let the user jump over to each of the listed classes to find
    out how `grok.name()` works in each of them.  My suspicion is that
    this is not yet a single-click operation with current technology,
    and that we will save people time by repeating ourselves.

I remember how much I enjoyed the D&D 3rd edition manual (not that I
actually played very much), because it did such a good job of repeating
facts everywhere it could be useful.  For example, if a Mage was not
good at a certain kind of travel, it would mention this both in the
description of the Mage class and also in the section on travel!  This
meant that you didn't have to "keep the whole book in your head"; and
while it imposed on their technical writers the duty of updating both
the class description and the section on travel when a fact about
how-the-Mage-travels changes, I suspect that it became pretty easy once
they thought of facts like that as connecting several objects or
subjects, each of which should be looked up when a rule was adjusted.

So.  Anyone with opinions should let me know what they think, before I
run off and write several-paragraph docstrings for anything.

Also: `grok.View` has a method `flash()` which has no documentation or
tests anywhere in the Grok code base (that I can find, at least).  Can
that be fixed, or should the method disappear?

-- 
Brandon Craig Rhodes   brandon at rhodesmill.org   http://rhodesmill.org/brandon