I'd like to fix up some details in the CMP regarding doxygen commenting,
as we seem to have evolved a slightly different technique from what the
CMP shows.
Things I'd like to address specifically:
--- CHANGE #1 -------------------------------------------------------
BEFORE:
/**
* The Foo class implements the Foo widget for FLTK.
*
* This description text appears in the documentation for
* the class and may include HTML tags as desired.
*/
SUGGESTED:
/**
The Foo class implements the Foo widget for FLTK.
This description text appears in the documentation for
the class and may include HTML tags as desired.
*/
RATIONALE:
There was discussion about the leading '*'s down the left margin.
Those for it (myself included) thought it was visually easier to
tell the difference between comments and code.
Those against had the compelling argument that the '*'s made it
hard to reformat paragraphs when docs were modified.
I'm suggesting this change be made not only because the reformatting
issue is both compelling and practical, but also the majority of our
docs doesn't have the '*'s.
I'm also suggesting two space indent for comments, consistent with
our general rule for indent.
I'm also suggesting the closing comment be a left justified '*/',
as again that seems to be what much of the docs use,
though personally I prefer seeing '**/' to make it visually easier
to see where the comment block ends. Not suggesting this though
because again, the majority of our code uses '*/'.
--- CHANGE #2 -------------------------------------------------------
BEFORE:
/**
* A brief description of the function/method.
*
* A complete description of the function/method.
*
* @param a What "a" is.
* @param b What "b" is.
* @return What this function/method returns.
* @see YourFunction()
*/
SUGGESTED:
/**
A brief description of the function/method.
A complete description of the function/method.
\param a What "a" is.
\param b What "b" is.
\return What this function/method returns.
\see your_function()
/
RATIONALE:
At least 95% of our code uses e.g. '\param' over '@param'.
(Only 38 lines of code uses @param, vs. >900 lines of \param).
Determined by:
$ grep '\param' src/*.cxx FL/*.H | wc | awk '{ print $1 }'
$ grep '@param' src/*.cxx FL/*.H | wc | awk '{ print $1 }'
--- CHANGE #3 -------------------------------------------------------
I'd like to add a section showing an example switch/case statement, eg:
SUGGESTED:
switch(var) { // braces follow CMP rules
case 1:
stuff_here(); // most common usage
break;
case 2: { // braces for variables: follow CMP
bracing rules
int var;
stuff_here();
break;
}
case 3:
stuff();
/* FALLTHROUGH */ // comment all fallthroughs!
case 4: simple_stuff1(); break; // one liners allowed IF non-complex
case 5: simple_stuff2(); break; // or for vertical alignment clarity
default:
break;
}
RATIONALE:
I've seen some very strange variations in case statements that do NOT
follow the general CMP, and I think this is because we don't have docs
that cover it.
---------------------------------------------------------------------
I have other doxygen additions I'd like to merge into the CMP,
(eg. the 'google docs' stuff we hashed out a year or so ago)
but would prefer to do that on another day.
If you have suggestions for other RFC's regarding the CMP,
please make a separate thread.
Requesting a vote to make the above changes.
_______________________________________________
fltk-dev mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-dev
