[Grok-dev] How complete should docstrings be?
Brandon Craig Rhodes
brandon at rhodesmill.org
Sun Jan 4 13:56:35 EST 2009
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
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
More information about the Grok-dev