Re: Doxygen patch

[Frans Englich]

On Sunday 03 September 2006 01:05, Satya wrote:
> hi,
> Here is a patch with some of the header files (most of them) with comments
> in the format acceptable by 'Doxygen' (http://www.doxygen.org). I have
> signed papers earlier and I am assigned to this project. Please let me know
> if you can commit the patch. More doxygenation will be coming along.
> Thanks.

Some comments:

* It's redundant to specify the file name when the @file tag is in the file 
being documented. For example, in assoc.h, just write "\file" instead 
of "\file assoc.h". This makes the code less error-prone, for example.

* There is editorial inconsistency. Some sentences start with a capitalized 
character. Some do not. Some sentences end with a period. Some do not. I 
would use proper sentences throughout. This seems to be here and there in the 
file.

* Some lines ends with whitespace. Search and remove.

* Have you checked the doxygen output for warnings? For example, 
for "%include" isn't "%include" put in the output, but "include" because "%" 
has special interpretation. You probably want %%include. There's some other 
case with % too.


Cheers,

                Frans