[Boxbackup-dev] doxygen

Mick Kappenburg boxbackup-dev at functions-net.nl
Thu Jan 14 14:05:11 GMT 2010


No patch like requested but an example and some explanation.

The easiest way would be to change all // 's to /// for all class and function 
documentation. For readability some spacing needs to be included, separating  
the different parts (Name, Purpose and Created). A newline after Function adds 
to its readability. The @returns gives a better formatted document. This 
process could be automated quite easily I guess. The comments would look 
something like the following:

/// --------------------------------------------------------------------------
///
/// Function \n
///		Name:    BackupStoreFile::EncodeFile(IOStream &, IOStream &)
///
///		Purpose: Encode a file into something for storing on file server.
///			 Requires a real filename so full info can be stored.
///
///			 @returns a stream. Most of the work is done by the stream
///			 when data is actually requested -- the file will be held
///			 open until the stream is deleted or the file finished.
///
///		Created: 2003/08/28
///
/// --------------------------------------------------------------------------

Sadly the easiest way is not close to the best way in my opinion. If you are 
unfamiliar with doxygen you could have a look at 
     http://www.stack.nl/~dimitri/doxygen/manual.html
I propose to drop the redundant 'function' and part and question the 'Created' 
date line (but maybe there is a reason for it which is not apparent for a 
newbie to the code). Of course doxygen's options should be used, changing 
above comment to:

/**
 * Encode a file into something for storing on file server.
 * Requires a real filename so full info can be stored.
 * @param Filename < description here >
 * @param ContainerID < description here >
 * @param rStoreFilename < description here >
 * @param pModificationTime < description here > default 0
 * @param pLogger < description here > default NULL
 * @param pRunStatusProvider < description here > default NULL
 *
 * @returns a stream. Most of the work is done by the stream
 *          when data is actually requested.
 * @note    The file will be held open until the stream is
 *          deleted or the file finished.
 *
 * @date Created: 2003/08/28
 */
(A box of * can be made on top and bottom if desired.)

An other thing about the documentation. It would be nice if all documentation 
would (at least) go in the header files. This makes the header file the only 
file needed to be inspected to understand what is going on. The cpp files then 
only reveal how it is done. At the present if you want to use the libs you 
need to read the cpp files for the comments and the header files for all code 
which is not in the cpp files, which turns out to be a lot (inline functions, 
class declarations etc.)

Regards,
MRK

> Hi MRK,
> 
> On Wed, 13 Jan 2010, boxbackup-dev at functions-net.nl wrote:
> > Is there a reason for not using Doxygen style comments?
> 
> I don't think it existed when work on Box Backup and the libraries was
> started.
> 
> > I find browsing through code an efficient way to get acquainted with new
> > code.  So if there are no objections lets start changing the comments.
> 
> I'm not familiar with Doxygen. Could you start by submitting patches with
> some examples of how to rewrite the comments in this way, so that we can
> see what the impact would be?
> 
> Cheers, Chris.
> 




More information about the Boxbackup-dev mailing list