On Wednesday, January 19, 2011 1:14:28 AM UTC-5, cjrh wrote: > > There was a malfunction on my link to the module-level documentation > that I was referring to (curse you Frames): first go here: > > http://www.web2py.com/examples/static/epydoc/index.html > > And then click on web2py.gluon.dal on the left. You will see module- > level documentation on the right, which is already prose-like and > descriptive. This is what I was referring to as a suggested location > for the "tour guide to the source code".
Yes, I agree, we should make use of the docstrings as much as possible. Though the plain text formatting isn't ideal -- for some docstrings, it would be nicer to use the epytext or reST markup that works with Epydoc (or maybe modify it to work with markmin, or migrate to an Epydoc alternative, as Epydoc is no longer under active development). There are also some topics that cut across multiple modules and therefore wouldn't easily fit into the Epydoc structure -- though, again, it would be nice if we could simply modify the structure a bit to get that material into the same interface rather than putting it elsewhere. Best, Anthony
