[Grok-dev] How complete should docstrings be?

[Reinout van Rees]

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

-- 
Reinout van Rees
http://reinout.vanrees.org/
http://photos.reinout.vanrees.org/