[IAEP] Alpha API Docs are up.

[Albert Cahalan]

On Mon, Jun 9, 2008 at 2:28 PM, David Farning <dfarning at gmail.com> wrote:
> On Mon, 2008-06-09 at 01:51 -0400, Albert Cahalan wrote:

>> Thanks for the effort. Please don't shoot the messenger, but...
>>
>> This is not proper API documentation. It's not complete, and not
>> at all organized. It's also not a good API as far as I can tell.
>>
> I have published the files I used to generate the APIs at
> http://www.sugarlabs.org/gitweb/pub
>
> The APIs are generated from docstrings in the original code which is
> available at http://dev.laptop.org/browser .
>
> Patches welcome.

No reasonable patch could possibly help.

The problem is with the concept. One can not
generate decent documentation by running code
through an automated extraction process.

Automation can get you a nice source browser.
See http://lxr.linux.no/ for an example.

For real documentation, there is no way to avoid
the writing effort. You need to use the word processor
of your choice (possibly involving TeX or *roff) and
just start writing. Documentation isn't easy. :-(