[Bf-committers] Doxygen (was CVS commit: blender/source/blender/imbuf/intern ...)

[Casey Corn]

> Hi Casey,
> 
> I never used doxygen, I'm also not a good reference
> user for it because  
> most of the code I know by heart! :)
> Nevertheless, can you post a monkey level
> instruction for me how to use  
> this?

I'm still figuring out the details of doxygen, but
probably the most useful thing for any coders (even
those who know the code by heart ;) ) is to write a
brief explaination of what exactly a chunk of code
does.

The easiest and most basic thing to do is:

/**
 * \brief This function does something.
 */
void function()
{
  do_some_stuff();
  do_some_more_stuff();
}

This is the minimum required to be useful.  The
"\brief" part of it distinguishes this explaination
from a more detailed comment.  It puts this part in
any list that the function belongs to.  If you wanted
to add a little more detail you would do something
like this:

/**
 * \brief This function does something.
 *
 * This function does some stuff, and then does more
 * stuff.
 */
void function()
{
  do_some_stuff();
  do_some_more_stuff();
}

Note: the extra line between "\brief ..." and "This
..." is required.
Alternately, you could do:

/**
 * \brief This function does something.
 */
void function()
{
  /**
   * This function does some stuff.
   */
  do_some_stuff();

  /**
   * Then, it does some more stuff.
   */
  do_some_more_stuff();
}

The second method keeps the documentation closer to
the code it describes.  You might not like this method
based on your comments below.  I documented some of
the function imb_loadamiga() in amiga.c this way.

I should mention, that this style requires the
documentation to be placed immediately before (in some
cases it can be on the same line as) the definition. 
Otherwise, the document would have to look like this:

/**
 * \fun void function()
 * \brief This function does something.
 *
 * This function does some stuff, and then does more
 * stuff.
 */

/* other code and/or documents */

void function()
{
  do_some_stuff();
  do_some_more_stuff();
}

In this way, it is possible completely document the
code without touching the sources.  The docs could
even be located in an entirely different file.  The
problem with having the docs seperate is that whenever
the code is changed, the coder must remember to change
the docs (or doc file) as well.

BTW, this is how the doc/doxygen.main file works.  The
text that exists in this file is global, so the need
to keep the code in sync with the docs is not present
in this case.  Besides, which file would it go in?

Back to documenting.  A more in depth example is:

/**
 * \brief This function takes x and returns an int
 * that means something.
 *
 * This function checks x for something and then
 * returns some flags based on x.
 * \param x This is how you would document a variable
 * \return Returns a flag based on x, or 0
 * if check() fails.
 */

int function(int x)
{
  if( check(x) == INVALID) return 0;

  return get_flag(x);
}

The \param command is for parameters, and the \return
command is for the return value.  There is also \pre
for preconditions, \post for post conditions, \warn
for warnings, and a whole host of other commands.

I should mention than none of these types of comments
will show up in the documentation unless the file that
contains the functions is also documented.  For files,
the doxygen comment would be like so:
/**
 * \file somefile.c
 * \brief This file contains functions that do things.
 */

That is the basics.  I have also defined a set of
groups which split the parts of blender into
categories.  They are defined in the doc/doxygen.main
file, towards the end.  For instance, each of the
files in imbuf I have added to the imbuf group like
so:

/**
 * \file imbuf_file.c
 * \ingroup imbuf
 * \brief This file contains imbuf functions.
 */

Groups can also be included in other groups.  For
instance, I was thinking of adding in a group called
imbuf_types to put the image format specific files
into.

Grouping is not necessary for doxygen to do it's job. 
You don't have to use groups ever, but sometimes it's
nice to have things listed by function.

I should also mention that the /** */ style is only my
preference.  You could also use
/*@ */
/*! */

and a few others which I don't see often, so I don't
remember them :) .

> Further, you should be aware of that documenting
> code should never  
> destroy its readability for coders or debuggers.
> What you did to  
> IMB_imbuf_types.h is really destroying a useful code
> layout. Especially  
> self-explaing #defines, or lists of data... also
> when 2 variables in a  
> struct are defined at the same line has
> functionality, and makes code  
> readable.
> 
> For doxygen to be acceptable, it should leave the
> code layout as simple  
> & readable as possible. Mixing comments in about
> every line makes  
> coding very user unfriendly. This can be done with a
> single block of  
> comments as well, preserving a readable and
> structured layout.
> 
> In my opinion code can be very self-explanatory,
> with comments required  
> only helping someone to understand it. When comments
> start to replace  
> (in fact duplicate) code, you're just going too far.

Yes, you are absolutely correct.  I got a little
carried away :) .  I also lost sight of what should be
my #1 goal: be as un-obtrusive as possible when
documenting.  This would include maintaining
readability.  I was (mistakenly) thinking only in
terms of what doxygen would generate.  I won't be able
to commit stuff until Monday afternoon, so I won't be
able to fix this right away.

> (I didn't check the other .h files yet, I just
> wanted to review the bug  
> report on compile errors in IMB_allocimbuf.h)
> 
> -Ton-

Well, in the other .h files I hope you'll be
pleasantly surprised :) .  In most cases, the one
comment line is a little redundent, but in one or two
cases, the .c file didn't have the same name as the .h
file.

I would really appreciate it if you would review the
function imb_loadamiga() in amiga.c, to see if I went
overboard there as well.  If you answer any of the
questions I put into the comments, that would be cool
as well :) .

Thank you for your feedback! (it's the only way I'll
get any better at this :) )
Casey

P.S.
I write most of my e-mails during dead time at work,
so depending on what I'm doing, it may take me a while
to respond to stuff.  Plus, I write slow :) .

__________________________________
Do you Yahoo!?
Yahoo! Calendar - Free online calendar with sync to Outlook(TM).
http://calendar.yahoo.com