[Zope3-dev] initial topics for z3 doc project

kapil thangavelu kvthan@wm.edu
Fri, 8 Nov 2002 03:05:05 -0800


On Thursday 07 November 2002 02:45 pm, holger krekel wrote:
> Guido Wesdorp wrote:
> > On Thursday 07 November 2002 10:51, holger krekel wrote:
> > > If all 'documentation' is available at runtime this makes it
> > > easier to have interactive search functions etc.  Maybe the
> > > Demo-Project project should really be a Zope3 product itself
> > > documenting itself.  Eat your own catfood.
> > > But that might mean we have to wait :-)
> >
> > Do one of you know how well the sources itself are documented? It would
> > help if the docstrings would be a little more consistent then in 2...
> > Maybe we can make sure extracting documentation from the sources will
> > lead to a clean and complete reference,  making sure arguments,
> > returnvalues etc. are described in the docstrings of either the objects
> > or the interfaces in a consistent manner. Or at least set some obligatory
> > style for docstrings or so...
>
> We could write a unittest for "correct" syntax of docstrings.
> Coincidentally, I talked to GvR about some python docstrings
> and a stricter syntax regarding the 'signature' line (the first
> of a docstring).

alternatively we could write a metaclass that checks to insure that interfaces 
are actually implemented, the interface should contain. the docs. i dunno how 
the metaclass checker would interact with persistent subclasses though.

-k