On Wed, Sep 24, 2008 at 5:30 PM, Marco Pesenti Gritti <[EMAIL PROTECTED]> wrote: > 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.
Sure. > Actually I'm not even sure we should use pydocweb for private docs. Perhaps not, I guess it depends on which advantages it brings. That kind of docs would only be edited and consumed by developers, of course. > Informal > documentation directly in the code (when writing or modifying it) would be > enough imo. And on some functions documentation might just add noise... What do you mean by informal documentation? Personally, I think that docstrings without implementation details are useful everywhere. And inline comments should only be used when we are doing a hack because of performance, working around a bug in some other component, etc Regards, Tomeu _______________________________________________ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar