[sugar] Now YOU can write API documentation

[Tomeu Vizoso]

On Wed, Sep 24, 2008 at 5:30 PM, Marco Pesenti Gritti
<mpgritti at gmail.com> wrote:
> 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.

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