RE: Documentation - doxygen (was Re: [Plib-devel] Work outstandin g.)

[Dave M. <Dav...@dy...>]

> Hi,
> 
> > I'd *really* like to help with this.  Documentation is a 
> pretty vital part
> > of getting newbies running, so I'll see what I can do in 
> this regard.  I'm
> > thinking of HTML page per class, with member variables and methods
> > documented.
> 
> Yes, the advantages of having the functions (and variables) 
> documented in the source code can't be under estimated.  I was first
> introduced to this when programing on the Amiga (all the 
> public OS functions were documented in this way).  It's _very_ useful.
> 
> It means that if someone adds a function they can document 
> before the cvs commit, and the documentation automatically 
> gets updated.
> And you won't believe the number of bugs you catch when you 
> start documenting  functions individually :)
> 
The Amiga used ROBODOC, which is what I'm using at work.
http://www.xs4all.nl/~rfsber/Robo/robodoc.html.  ROBODoc can format the
documentation in HTML, ASCII, AmigaGuide, LaTeX, or RTF format. It is even
possible to include parts of the source code with function names that point
their the documentation. It also can create index tables for all your
variables, classes, functions, etc.  for example:

/****f* ROBODoc/RB_Add_Link [3.0b]
 * NAME
 *   RB_Add_Link -- add a reference link to the list
 * SYNOPSIS
 *   void RB_Add_Link ()
 * FUNCTION
 *   Adds a reference from a xref file to the linked list
 *   with references.
 * INPUTS
 *   Uses the global variable line_buffer and first_link.
 * NOTES
 *   Makes sneaky use of the function RB_Insert_In_List.
 * SEE ALSO
 *   RB_Analyse_Xrefs, RB_link.
 * SOURCE
 */

The syntax of ROBODOC headers is more natural looking than other auto-doc
generators, IMO.  You can use the keywords INPUTS, ARGUMENTS, and PARAMETERS
interchangeably.  Same goes for FUNCTION, DESCRIPTION, and PURPOSE.  I
ported RoboDOC to windows if you want it.  Frans may have that in the latest
release, but I'm not sure.

--Dave