Updates API documentation for everything.

[Mitch Bradley]

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

The basic Open Firmware level is reasonably well documented -

  http://docs.sun.com/app/docs/doc/805-4436
  http://firmworks.com/QuickRef.html

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.

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

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.

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