On Wed, Mar 26, 2003 at 12:55:13AM +0000, Jos� Fonseca wrote:
[...]
> I'd also want to take this opportunity to request that everybody who
> writes new code to follow a few simple conventions - this will enable
> automatic documentation extraction by the Doxygen tool as above -, but
> I'll do that in a seperate email tomorrow, together with a brief
> tutorial.
Hmm.. time does fly. Anyway, here is the promised brief Doxygen
tutorial.
Special comments blocks are marked with a double asterisk as /** ... */,
or /**< ... */ if they follow the member. Special tags within the
special comments are marked with a slash '\', of which the most
important is '\brief'. The minimum ammount of documentation for all
non-trivial code is a special comment with just a 'brief' tag:
/** \brief The structure of the universe */
struct Universe {
unsigned long nAtoms; /**< \brief Number of atoms */
struct Atom *atoms; /**< \brief The state of each atom */
} ;
/** \brief Is Earth flat? */
void isEarthFlat(void) {
return getCentury() < 16;
}
Also, all files should start with a block like this:
/**
* \file internet.c
* \brief Implementation of the internet.
*
* \author Al Gore.
*/
This minimum ammount of documentation will mark these
structures/functions/files to be extracted by Doxygen and therefore
appearing in the generated documentation.
If you have more detailed documentation to give, or want to document a
certain parameter of the function return value you can do it like:
/**
* \brief Work simulation.
*
* This function simulates a working day using a highly sofisticated
* algorithm.
*
* \param n number of working hours.
*
* \return one on a productive day, zero otherwise.
*/
int work(int t) {
int i;
if (deadLine != gettimeofday()) {
while(!workDone) {
workVeryHard();
}
return 1;
} else {
checkEMail();
browseInternet();
for(i = 2; i < t - 1; i++) {
checkEMail();
tryToWork();
checkEMail();
usleep(aWhile*1000);
}
checkEMail();
pretendToWork();
return 0;
}
}
With many functions or structure fields is useful to group them together. This
can be done using the '\name' and {@ @} tags:
/** \brief
struct WarAnalysisRec {
/** \name Economic factors */
/[EMAIL PROTECTED]/
double priceOil; /**< \brief Price of oil per gallon */
double weapons; /**< \brief Estimated expenditure with
weapons */
/[EMAIL PROTECTED]/
/** \name Social factors */
/[EMAIL PROTECTED]/
unsigned char costHumanLife; /**< \brief Cost of human life */
/[EMAIL PROTECTED]/
void *privData; /**< \brief Private data pointer to an
opaque structure. */
} ;
Note that this grouping can't be nested.
There are more nice things that can be done, but these are the basic and
that give the most bang per buck. To know more info read the Doxygen
manual: http://www.stack.nl/~dimitri/doxygen/manual.html .
Those of you which already had some experience with Doxygen will notice
that some of thing present here don't necessarily have to be done this
way - Doxygen is a very flexible tool to suit different purposes - but
these are more or less the convetions used so far.
/**********************************************************************/
/** \name Read - Important */
/**********************************************************************/
/[EMAIL PROTECTED]/
I really ask for the Doxygen markup being used in _every_ new piece of
code in the DRI/Mesa project, regardless of how complete is the
surrounding documentation. Let's assume that _all_ code will be
documented so whatever can be done now is less work to be done later.
Yes, there _is_ a real benefit in having all the code documented.
Doxygen allows to produce documentation cross-referenced with the source
code, making a wonderfull source browsing tool for someone wanting to
study the code. Specifications as the ones found on
http://dri.sf.net/doc are good for an initial draft but they require
constant and time-consuming maintaince, and eventually get obsolete.
Code documentation is not only easier to maintain - by updating
simultaneously with the code -, as also benefits from the same
versioning as the code.
/[EMAIL PROTECTED]/
I hope I have give a good taste of source code documenting with Doxygen,
and made a good case for support for using it.
Jos� Fonseca
-------------------------------------------------------
This SF.net email is sponsored by: ValueWeb:
Dedicated Hosting for just $79/mo with 500 GB of bandwidth!
No other company gives more support or power for your dedicated server
http://click.atdmt.com/AFF/go/sdnxxaff00300020aff/direct/01/
_______________________________________________
Dri-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/dri-devel
