[Grok-dev] Re: grok reference - what needs to be documented and what not

[Martijn Faassen]

Hey,

Jan-Wijbrand Kolman wrote:
> I have started on the grok reference, getting familiar with the latex
> syntax, and the reference's content structure.

Excellent!

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

Regards,

Martijn