+1
On Dec 2, 2010, at 8:27 AM, Greg Ercolano wrote:
> 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
________________________________________
Michael Sweet, Easy Software Products
_______________________________________________
fltk-dev mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-dev
