[sugar] Now YOU can write API documentation

[Marco Pesenti Gritti]

Tomeu Vizoso wrote:
> On Wed, Sep 24, 2008 at 3:12 PM, David Farning <dfarning at sugarlabs.org> 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