[Grok-dev] How complete should docstrings be?
Reinout van Rees
reinout at vanrees.org
Sat Jan 3 21:35:21 EST 2009
Brandon Craig Rhodes schreef:
> 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`.
5: Such duplication carries a risk of getting out of sync.
4: Yeah, generating such documentation from the code is a good idea,
especially when you've got lists of things (like directives). It is
soooo easy to forget one or more.
For Plone's archgenxml tool I got tired of keeping the documentation of
UML tagged values and stereotypes in sync with the code. So I made sure
that the up-to-date list of both could be exported from the code and
pasted into the plone help center. Never had a problem with it afterwards.
Reinout van Rees
More information about the Grok-dev