[Grok-dev] How complete should docstrings be?
Brandon Craig Rhodes
brandon at rhodesmill.org
Sat Jan 3 10:16:59 EST 2009
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
More information about the Grok-dev