[Boxbackup-dev] doxygen

Mick Kappenburg boxbackup-dev at functions-net.nl
Tue Jan 19 15:58:52 GMT 2010


I created a script for changing the comment.
The comment is converted to the /** ... */ example (no extra text, like param, 
is added).

It worked for me (with convertComment as attached):
find -name \*.h   -exec bash -c '~/convertComment < {} > {}.new;mv {}.new {} 
&& echo {}' \;

Regards,
MRK

 On Thursday 14 January 2010, Mick Kappenburg wrote:
> 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.
> 
> _______________________________________________
> Boxbackup-dev mailing list
> Boxbackup-dev at boxbackup.org
> http://lists.boxbackup.org/cgi-bin/mailman/listinfo/boxbackup-dev
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: convertComment.gz
Type: application/x-gzip
Size: 736 bytes
Desc: not available
URL: <http://lists.boxbackup.org/pipermail/boxbackup-dev/attachments/20100119/ba1ae7e4/attachment.bin>


More information about the Boxbackup-dev mailing list