[Grok-dev] Re: grok reference - what needs to be documented and
faassen at startifact.com
Tue May 29 08:51:41 EDT 2007
Jan-Wijbrand Kolman wrote:
> I have started on the grok reference, getting familiar with the latex
> syntax, and the reference's content structure.
> First question: Do you expect *all* functions and classes etc. to be
> documented, or "only" the ones that a developer *with* grok gets in
> contact with?
Only the public functions and classes. Other functions and methods are
implementation details and should not be documented, as we want to be
able to change them.
> As an example: I started with the url() function in util.py. This is,
> as far as I can see, the only function in this module that a regular
> developer will need from this module. The fact that it is imported in
> __init__ illustrates this.
> Would that actually be a usefull guide: "The reference will document
> everything that is imported in __init__?"
Yes. Almost all is published through __init__.py and should also be
documented in interfaces.py. Not everything though - the catalog index
declaration code isn't, for instance, and there may be other cases.
For methods you can't rely on __init__.py, of course. Here interfaces.py
should serve as a guide. Feel free to update interfaces.py by the way -
some of the reference text might make sense there.
More information about the Grok-dev