[IAEP] Alpha API Docs are up.

[Martin Dengler]

On Mon, Jun 09, 2008 at 10:29:43PM -0400, Albert Cahalan wrote:
> 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.

Sounds like you're begging the question.

I'm not sure anyone's going to disagree that hand-written
documentation has the potential to be much better.  But the
fundamental approach of generating API reference documentation
starting from something auto-generated has good working
examples[1,2,3].

> 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.

If someone is willing to do that, or implement a framework a bit more
advanced that *TeX/*roff (or a corpus of templates in those/similar
formats to start from), perhaps someone would be willing to start
expanding that and filling it in.

Martin

1. http://sphinx.pocoo.org/ext/autodoc.html
2. http://www.ruby-doc.org/stdlib/
3. http://dbus.freedesktop.org/doc/api/html/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.lo-res.org/pipermail/its.an.education.project/attachments/20080610/4b00dadb/attachment.pgp>