Kendall Clark wrote: > jeffrey> 1. Documentation - it would help to see what core set(s) of > jeffrey> methods make up servlet use, and which methods are > jeffrey> particular to special servlet implementations. > > and toward this same end -- > > I think it would help if someone could run pydoc (or one of the python > documenting tools) over the Webware source and put the result on the > site. I've been working on some "So you wanna write a webware app" > notes, for a series of articles I'm gonna sell to O'Reilly, and the > existing API documentation is rather unhelpful. Sure, I can 'just use > the source', which I'm doing. But I find the combo of API docs and the > source the best approach, personally. > > I especially like Ka-Ping Yee's API (HTML) output; any chance we can > get that on the Webware site?
Let's not make this a one-off. Instead, pydoc or other documentation tools should be run on the Python source automatically as part of running "python install.py" (or "python setup.py install" in the future). "python install.py" already makes some attempt at generating summaries from the source files, but I don't find the generated output to be very useful. It doesn't include the docstrings, for example. Here's the kind of output it generates currently: http://webware.sourceforge.net/Webware-0.7/WebKit/Docs/Source/ClassHier.html If anyone wants to improve these generated summaries, I'd be very happy to accept the patches. Then, it's a matter of improving the docstrings. We should strive to have all methods that are part of the public interface be clearly identified as such, and also to be well documented. (And tested via automated tests.) - Geoff _______________________________________________ Webware-discuss mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/webware-discuss
