[Grok-dev] How complete should docstrings be?

[Brandon Craig Rhodes]

Reinout van Rees <reinout at vanrees.org> writes:

>>  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.

You're right.  Maybe instead each directive should just name the Grok
classes that it works with, then each class, like `grok.View`, can be
where the actual explanation goes of how the directives should be used.
I think that makes the most sense, since a directive might have a
different default or even a slightly different meaning when used with
different classes.

So, I'll avoid the duplication I was threatening to create, and we'll
see if we get useful docstrings anyway.  Thanks!

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