[IAEP] Alpha API Docs are up.
martin at martindengler.com
Tue Jun 10 05:27:48 CEST 2008
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
> 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: not available
More information about the Its.an.education.project