Doxygen API documentation
Martin Pool
mbp at samba.org
Thu Nov 15 15:36:06 GMT 2001
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
More information about the samba-technical
mailing list