Updates API documentation for everything.

[Edward Cherlin]

First, thanks to everybody who replied to my requests on Python,
Smalltalk, and FORTH documentation tools. I will put the links you
have given me into the document outlines linked from the OLPC
Publications page, and at some point we can start expanding the
outlines into draft documents. Further comments on these Wiki pages
will be greatly appreciated.

On Jan 1, 2008 3:50 PM, Mitch Bradley <wmb at laptop.org> wrote:
> Edward Cherlin wrote:
> >
> >> Does anybody know of a documentation tool for Open Firmware, or for
> >> FORTH more generally? Exploring using 'words' and 'see'
> >>
> >
> > is fun up to a point if you're learning FORTH, but really doesn't cut
> > it for supporting documentation.
> >
>
>
> I presume that you have seen the tutorials at
>
>   http://wiki.laptop.org/go/Forth_Lessons

Yes. And I programmed in FORTH many years ago.

> The basic Open Firmware level is reasonably well documented -
>
>   http://docs.sun.com/app/docs/doc/805-4436
>   http://firmworks.com/QuickRef.html

That's what I mean. Thanks.

> The OLPC-specific stuff could certainly use some additional
> documentation.  The source code for the OLPC-specific stuff has some
> amount of internal documentation that could be extracted.  Each source
> file has a "purpose" comment at the top of the file, and many of the
> individual word definitions are preceded by a brief description.  For
> example, the file cpu/x86/pc/olpc.fth begins with:
>
>   purpose: Determine the board revision based on hardware and EC info
>
> and that file defines the word "model-name$" as follows:
>
>   \ Constructs a string like "B4" or "preB4" or "postB4"
>  : model-name$  ( -- model$ )
>
> Many, but certainly not all, of the words that can plausibly be used
> interactively have brief description strings like that.
>
> Some words don't have brief descriptions in the source, and probably
> never will have them, based on the clarity of their names .  For
> example, for the word "bios-checksum-bad?  ( -- flag )", I didn't feel
> compelled to write "\ Returns true if the BIOS checksum is bad".  The
> various "xxx@" and "xxx!" words fall into that category, once you know
> the general pattern of "@" and "!".  But even so, it would be nice to
> have a compendium of those words with English descriptions for easy
> reference.

Exactly. It should be fairly easy to do.

> I'm not a big fan of automated documentation tools.  They can help with
> the mechanics of extracting documentation strings from source code, but
> in my experience, such documentation is only marginally useful.  The
> really hard part of understanding how something works is the contextual
> stuff - the circumstances under which it is appropriate to call a given
> function, how it fits together with related stuff, etc.

Exactly. I have been working as an API Tech Writer for most of the
last decade. Getting decent sample code out of developers has always
been the hardest part of the job, and frequently I just had to write
it myself.

> Phrases are
> more enlightening than individual words.  Automated documentation
> extraction tends to describe individual trees, leaving you wondering
> about the overall shape of the forest.  Projects that are set up for
> auto doc tools tend to have long structured comment blocks before every
> function.  The individual fields are often extremely boring - like
> "Outputs: none", and the overall size of the comment block takes up so
> much screen real estate that the actual code is lost among the boilerplate.
>
> Going back to the "bios-checksum-bad?  ( -- flag )" example, the usual
> tendency would be to say something obviously correct, and entirely
> pointless, like "Returns a boolean flag that is true if the BIOS
> checksum is bad".  What really should be said is something like:
>
> Conventional PC BIOSes checksum the CMOS RAM between indices 0x10 and
> 0x2d inclusive, storing the arithmetic sum as a 2-byte big-endian
> integer at indices 0x2e and 0x2f.  "bios-checksum-bad?" tests that
> checksum.  It is an implementation factor of "init-bios-cmos", which
> ensures that said checksum is correct,  fixing the checksum by zeroing
> that entire area if not.
>
> But of course people rarely write documentation that complete, for any
> number of reasons.

Are you putting your hand up?

> That said, I really need to go through all the new OLPC code and at
> least add brief descriptions for all the top-level words.

Ah. Evidently Yes. Thanks.

> Meanwhile, if anyone wants to look at the source code, the OLPC-specific
> bits are mostly collected in a few directories, primarily
> cpu/x86/build/olpc/  and dev/olpc/*
>
> The source tree is at http://openbios.org/Open_Firmware

Very good.

Thanks again, and Happy New Year.

-- 
Edward Cherlin
Earth Treasury: End Poverty at a Profit
http://www.EarthTreasury.org/
"The best way to predict the future is to invent it."--Alan Kay