Tomeu Vizoso wrote: > On Wed, Sep 24, 2008 at 3:12 PM, David Farning <[EMAIL PROTECTED]> wrote: > >> On Wed, 2008-09-24 at 13:55 +0200, Morgan Collett wrote: >> >>>> thanks >>>> david >>>> >>> I've started on sugar.network as I went through that code recently. >>> >>> Here's an issue with pydocweb: >>> http://sugarlabs1.xen.prgmr.com/pydocweb/doc/sugar.network.GlibTCPServer/ >>> doesn't show the name of a method starting with _ - _handle_accept. I >>> knew it existed, so I manually edited the URL to >>> get to >>> http://sugarlabs1.xen.prgmr.com/pydocweb/doc/sugar.network.GlibTCPServer._handle_accept/ >>> which I edited. >>> >>> Bug? Feature? >>> >>> >> It is a feature. Pydocweb is set to not publish private methods and >> classes. The idea is to create the documentation that is most >> appreciated by application developers. Should we change this? >> > > I think that we should start by adding docstrings to the public API in > sugar.*, then document the shell's public classes and methods, and > finally lift that limitation and add docstrings to all the private > methods. >
The generated documentation should only contain public methods. Actually I'm not even sure we should use pydocweb for private docs. Informal documentation directly in the code (when writing or modifying it) would be enough imo. And on some functions documentation might just add noise... Marco _______________________________________________ Sugar mailing list [email protected] http://lists.laptop.org/listinfo/sugar
