Doxygen API documentation

[Martin Pool]

I've just put a configuration file into HEAD to run the Doxygen API
documentation generator.  Please, have a look around the documentation
here:

  http://samba.org/~mbp/samba-dox/

To recreate this yourself, do

  # apt-get install doxygen graphviz
  (or on other systems download and install from doxygen.org)

  $ cd head/source
  $ cvs update
  $ doxygen

  (make coffee)

  $ netscape dox/html/index.html

Doxygen produces HTML output that contains both cross-referenced
program source code, and API documentation generated from
specially-marked program comments.  At the moment most of Samba
doesn't have that markup, but the cross-referenced listings and API
prototypes are still pretty useful.

One area that is already marked up is Richard Sharpe's libsmbclient:

  http://samba.org/~mbp/samba-dox/group__file.html

It's also a good example of how you can fairly easily add or convert
some source code comments to provide an excellent resource for other
people who might be working on or using that area of Samba.  From
libsmbclient.h:

/**@ingroup structure
 * Authentication callback function type.
 * 
 * Type for the the authentication function called by the library to
 * obtain authentication credentals
 *
 * @param srv       Server being authenticated to
 *
 * @param shr       Share being authenticated to
 *
 * @param wg        Pointer to buffer containing a "hint" for the
 *                  workgroup to be authenticated.  Should be filled in
 *                  with the correct workgroup if the hint is wrong.
 * 
 * @param wglen     The size of the workgroup buffer in bytes
 *
 * @param un        Pointer to buffer containing a "hint" for the
 *                  user name to be use for authentication. Should be
 *                  filled in with the correct workgroup if the hint is
 *                  wrong.
 * 
 * @param unlen     The size of the username buffer in bytes
 *
 * @param pw        Pointer to buffer containing to which password 
 *                  copied
 * 
 * @param pwlen     The size of the password buffer in bytes
 *           
 */

Basically if you just change the "/*" to "/**" at the start of every
comment that is external, rather than implementation documentation
then the text will come out into the HTML pages.  There are lots of
other tags like @param documented at doxygen.org, but you don't need
them to get going.

-- 
Martin