Author: greg.ercolano
Date: 2012-03-04 18:59:53 -0800 (Sun, 04 Mar 2012)
New Revision: 660
Log:
Merged the google docs modifications into the CMP.
- Covers Doxygen comment style specifics for 1.3.x
- Covers new FLTK_ABI_VERSION macro
All new additions in 'wine red' to allow easy viewing of what's changed.
Modified:
trunk/cmp.php
trunk/fltk.css
Modified: trunk/cmp.php
===================================================================
--- trunk/cmp.php 2012-02-25 17:37:26 UTC (rev 659)
+++ trunk/cmp.php 2012-03-05 02:59:53 UTC (rev 660)
@@ -21,29 +21,26 @@
<ul>
- <li><a href="#INTRODUCTION">Introduction</a></li>
+ <li><a href="#INTRODUCTION">Introduction</a></li>
- <li><a href="#COMMUNICATION">Communication</a></li>
+ <li><a href="#COMMUNICATION">Communication</a></li>
- <li><a href="#SPECIFIC_GOALS">Specific Goals</a></li>
+ <li><a href="#SPECIFIC_GOALS">Specific Goals</a></li>
- <li><a href="#SOFTWARE_DEVELOPMENT_PRACTICES">Software
- Development Practices</a>
- <ul>
- <li><a href="#RELEASE">FLTK Release Process</a></li>
- </ul></li>
+ <li><a href="#SOFTWARE_DEVELOPMENT_PRACTICES">Software Development
Practices</a>
+ <ul>
+ <li><a href="#RELEASE">FLTK Release Process</a></li>
+ </ul></li>
- <li><a href="#TROUBLE_REPORT_PROCESSING">Trouble Report
- Processing</a></li>
+ <li><a href="#TROUBLE_REPORT_PROCESSING">Trouble Report Processing</a></li>
- <li><a href="#SOFTWARE_RELEASES">Software
- Releases</a></li>
+ <li><a href="#SOFTWARE_RELEASES">Software Releases</a></li>
- <li><a href="#FILE_MANAGEMENT">File Management</a></li>
+ <li><a href="#FILE_MANAGEMENT">File Management</a></li>
- <li><a href="#CODING_STANDARDS">Coding Standards</a></li>
+ <li><a href="#CODING_STANDARDS">Coding Standards</a></li>
- <li><a href="#MAKEFILES">Makefile Standards</a></li>
+ <li><a href="#MAKEFILES">Makefile Standards</a></li>
</ul>
@@ -618,19 +615,56 @@
are generated at weekly intervals until all level 4/5 trouble
reports are resolved.
-<h3>Production Releases</h3>
+<h3><a name="PRODUCTION_RELEASES">Production Releases</a></h3>
<p>Production releases are generated after a successful release
candidate and represent a stable release of the software
suitable for all users.
-<h3>Patch Releases</h3>
+<ul class='new'>
-<p>Patch releases are generated to fix priority 2-5 STRs. Patch
-releases may not add additional functionality from priority 1
-STRs.</p>
+ <h3><a name="MAJOR_RELEASES">Major Releases (Version #.x.x)</h3>
+ <p>
+ Major Releases occur when there's a major rewrite of the code, or a
significant
+ redefinintion of the API.
+ </p>
+ <h3><a name="MINOR_RELEASES">Minor Releases (Version x.#.x)</a></h3>
+ Minor Releases add ABI breaking features/fixes. Rarely breaks the API in
any
+ significant way.
+ <p>
+ Any <a href="#FLTK_ABI_VERSION">FLTK_ABI_VERSION</a> code should be
resolved
+ in Minor Releases. Any code that looks like:
+ <pre class='command'>
+ #if FLTK_ABI_VERSION >= 10305
+ ... new ABI breaking code ...
+ #else
+ ... old non-ABI breaking code ...
+ #endif
+ </pre>
+ ..is 'resolved' by <i>removing</i> the <tt>#if/#else/#endif</tt> and
+ <tt>'old non-ABI breaking code'</tt>,
+ so that only the <tt>'new ABI breaking code'</tt> is left in its
+ place for default builds.
+ <p>
+ <h3><a name="PATCH_RELEASES">Patch Releases (Version x.x.#)</a></h3>
+ <p>Patch releases are generated to fix priority 2-5 STRs. Patch
+ releases may not add additional functionality from priority 1 STRs.
+ <p>
+ Patch Releases fix small problems that don't break the ABI,
+ and must be API backwards compatible.
+ <p>
+ ABI breaking fixes/features can be added using
+ <a href="#FLTK_ABI_VERSION">FLTK_ABI_VERSION</a> to #ifdef out
+ the code from default builds, but can be optionally enabled
+ by end users who need it for testing or for static builds.
+ This can be done by defining this variable to the right
+ ABI version number in FL/Enumerations.H, and re-building
+ FLTK and their apps.
+ </p>
+</ul>
+
<h1><a name="FILE_MANAGEMENT">File Management</a></h1>
<p>This section describes how project files and directories are
@@ -852,36 +886,43 @@
<p>The purpose of the trailer is to indicate the end of the
source file so that truncations are immediately obvious.
-<h2>Documentation (Comments)</h2>
+<h2>Documentation (Comments) <a
href="#DEVELOPER_REFERENCE_COMMENT_STYLE">*</a></h2>
-<p>FLTK 2.0 uses Doxygen with the JavaDoc comment style to
+<p>FLTK 2.0 <a class=new>and FLTK 1.3 and up</a> uses Doxygen with the JavaDoc
comment style to
document all classes, structures, enumerations, methods, and
functions. Doxygen comments are <b>mandatory</b> for all FLTK
header and source files, and no FLTK release will be made
without complete documentation of public APIs. Here is an
example of the Doxygen comment style:</p>
-<pre>
- /**
- 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.
- */
+<pre class=new>
+/**
+ The Foo class implements the Foo widget for FLTK.
- class FL_EXPORT Foo : public Widget {
- int private_data_;
+ This description text appears in the documentation for
+ the class and may include HTML tags as desired.
+*/
- public:
+class FL_EXPORT Foo : public Widget {
+ int private_data_;
- /**
- Creates a Foo widget with the given position and label.
-
- This description text appears in the documentation for the
- method.
- */
- Foo(int X, int Y, int W, int H, const char *L = 0);
- };
+public:
+ /**
+ Creates a Foo widget with the given position and label.
+
+ This description text appears in the documentation for the
+ method's implementation.
+
+ References to parameters \p X, \p Y, \p W, \p H are
+ mentioned this way.
+
+ \param[in] X,Y,W,H Position and size of widget
+ \param[in] L Optional label (default is 0 for no label)
+ */
+ Foo(int X, int Y, int W, int H, const char *L = 0) {
+ ..implementation here..
+ }
+};
</pre>
<p>Essentially, a comment starting with <tt>/**</tt> before the
@@ -897,8 +938,99 @@
read, maintain, and debug the code.
<p><b>Never</b> use C++ comments in C code files or in header
-files that may be included from a C program.
+files that may be included from a C program. (Otherwise builds
+on strict platforms like SGI will fail).
+<a class=new>
+Normally, fltk C files have ".c" and ".h" file extensions, and C++ have
+".cxx" and ".H". Currently there are a few exceptions; filename.H and
+Fl_Exports.H both get interpreted by C and C++, so you <I>must</I> use C style
+comments in those.
+</a>
+<h2>General Developer Recommendations <a
href="#DEVELOPER_REFERENCE_GENERAL">*</a></h2>
+<ul class=new>
+ Most important rule: <b>Put Doxygen comments where the code's
implementation is.</b>
+ This means don't put the docs with the prototypes in the .H file, unless
that's where
+ the code is implemented.
+ <p>
+ <li> class, typedef, enum, and inline docs go in the headers</li>
+ <li> Most other docs go in the source files</li>
+ <li> For doxygen syntax in C++ files, use:
+ <pre class='command'>
+ /** for standard dox comments */
+ ///< for single line post-declaration short dox comments
+ </pre>
+ </li>
+ <li> For doxygen syntax in C files, use:
+ <pre class='command'>
+ /** for standard dox comments */
+ /**< for single line post-declaration short dox comments */</pre>
+ </li>
+ <li> Use <tt>\p</tt> for parameters citation in the description</li>
+ <li> Use <tt>\param[in] xxx</tt> and <tt>\param[out] xxx</tt> for
input/output parameters.</li>
+ <li> Don't use doxygen tags between the <tt>\htmlonly</tt> and
<tt>\endhmltonly</tt> pair of tags.</li>
+ <li> When commenting out code or writing non-doxygen comments, be sure not
to accidentally
+ use doxygen comment styles, or your comments will be published..!
Beware doxygen recognizes
+ other comment styles for itself:
+ <pre class='command'>
+ /*! beware */
+ /*@ beware */
+ //! beware
+ //@ beware</pre>
+ There may be others. For this reason, <i>follow all non-doxygen comments
leaders with a space</i>
+ to avoid doxygen parsing:
+ <pre class='command'>
+ /* safe from doxygen */
+ // safe from doxygen
+ ^
+ /|\
+ |
+ <i>Space immediately after comment characters</i></pre></li>
+ <li> Note: Several characters are 'special' within doxygen commments, and
must be escaped
+ with a backslash to appear in the docs correctly. Some of these are:
+ <pre class='command'>
+ \< -- disambiguates html tags
+ \> -- ""
+ \& -- ""
+ \@ -- disambiguates JavaDoc doxygen comments
+ \$ -- disambiguates environment variable expansions
+ \# -- disambiguates references to documented entities
+ \% -- prevents auto-linking
+ \\ -- escapes the escape character</pre>
+ </li>
+ <li> Itemized lists can be specified two ways; both work, left is
preferred:</li>
+ <p>
+ <table class=simple-table><tr>
+ <th>- Preferred -</th>
+ <th>- Old -</th>
+ <tr>
+ <td valign=top class='new'><pre class='command'>
+/** Here's a bullet list: <!-- space -->
+
+ - Apples
+ - Oranges
+
+ Here's a numbered list:
+
+ -# First thing
+ -# Second thing
+
+ */</pre></td>
+ <td valign=top class='new'><pre class='command'>
+/** Here's a bullet list: <!-- space -->
+ <ul>
+ <li> Apples</li>
+ <li> Oranges</li>
+ </ul>
+ Here's a numbered list:
+ <ol>
+ <li> First thing</li>
+ <li> Second thing</li>
+ <ol>
+ */</pre></td>
+ </tr></table>
+</ul>
+
<h3>Documenting Temporary Code or Issues</h3>
<p>Temporary code and code that has a known issue MUST be
@@ -944,72 +1076,123 @@
</pre>
<p>Each enumeration value must be documented in-line next to the
-corresponding definition as follows:
+corresponding definition as follows:<pre class='command'><a class='new'>/* C++
STYLE */
+enum MyEnum {
+ BLACK, ///< The color black.
+ RED, ///< The color red.
+ GREEN, ///< The color green.
+ YELLOW, ///< The color yellow.
+ BLUE, ///< The color blue.
+};</a></pre>
+<p>
+If the enum is included in a C file, be sure to use C style commenting:<pre
class='command'><a class='new'>/* C STYLE */
+enum MyEnum {
+ BLACK, /**< The color black. */
+ RED, /**< The color red. */
+ GREEN, /**< The color green. */
+ YELLOW, /**< The color yellow. */
+ BLUE, /**< The color blue. */
+};</a></pre>
-<pre>
- enum MyEnum {
- BLACK, /**< The color black. */
- RED, /**< The color red. */
- GREEN, /**< The color green. */
- YELLOW, /**< The color yellow. */
- BLUE, /**< The color blue. */
- MAGENTA, /**< The color magenta. */
- CYAN, /**< The color cyan. */
- WHITE /**< The color white. */
- };
-</pre>
-
<h3>Documenting Functions and Methods</h3>
<p>Functions and methods start with a comment block that looks
like the following:
+<pre><a class='new'>
+/**
+ A brief description of the function/method.
-<pre>
- /**
- 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()
- */
- int my_function(int a, float b) {
- ...
- }
+ A complete description of the function/method.
+ Optional passing mention of parameter <b>\p a</b> and <b>\p out1</b>.
+
+ Optional code example goes here if needed:
+ <b>\code</b>
+ ..code showing how to use it..
+ <b>\endcode</b>
+
+ <b>\param[in] a</b> Description of input variable a
+ <b>\param[in] x,y</b> Description of input variables x and y in one comment
+ <b>\param[out] out1</b> Description of output variable out1
+ <b>\param[out] out2</b> Description of output variable out2
+ <b>\return</b> 0 on success, -1 on error
+ <b>\see</b> other_func1(), other_func2()
+*/
+int my_function(int a, int x, int y, float &out1, float &out2) {
+ ...implementation...
+}</a>
</pre>
+<a class='new'>
+Some details on the above:
+<p>
+<b>Parameters</b>
+<ul>
+ Use <b>\param</b> to document function/method parameters
+ using either of the following formats, the latter being
preferred:<p><pre class='command'>
+ <b>\param var</b> Some description
+ <b>\param[in|out] var</b> Some description.
+ </pre>
+ Mention of parameters in docs should use "\p varname". (Use \p instead
of \a)
+ <p>
+ Note: Doxygen checks your \param variable names against the actual
function signatures
+ in your code. It does <u>NOT</u> check \p names for consistency.
+ <p>
+</ul>
-<p>Each parameter is documented using <code>\param</code>
-comments. The return value is documenting using the
-<code>\return</code> comment; omit the return value comment if
-the function/method does not return a value or is a constructor.
-The <code>\see</code> comments refer to other, related
-functions/methods.
+<b>Return Values</b>
+<ul>
+ Use <b>\return</b> to document return values. Omit this if there is no
return value.
+</ul>
-<p>Function/method documentation must be placed next to the
-corresponding code. Comments for in-line functions and methods
-in header files are placed in the header file.
+<b>Reference related methods</b>
+<ul>
+ <p>
+ Use <b>\see</b> to help the reader find related methods.
+ (Methods are sorted alphabetically by doxygen, so 'related' methods
might not
+ appear together)
+ <p>
+ Locate <b>\see</b> references below \param[] and \return as shown
+ in the above example.
+</ul>
+<b>Code examples</b>
+<ul>
+ Use <b>\code</b> and <b>\endcode</b> when code examples are needed.
+ Text within will be exempt from html and doxygen escape code parsing,
+ so you don't have to escape characters <, >, &, etc.
+ as you would normally.
+ <p>
+ Be careful not to embed C style comments within <b>\code</b>
+ or it will break the outer doxygen comment block. (A good reason
+ to always test build the code base before commiting documentation-only
mods)
+</ul>
+
+<b>Where to put docs</b>
+<ul>
+ Function/method documentation must be placed next to the corresponding
code.
+ (Rule: "Put the docs where the code implementation is.")
+ Comments for in-line functions and methods are placed in the header file
where they're defined.
+</ul>
+</a>
+
<h3>Documenting Members and Variables</h3>
-<p>Members and variables can be documented in one of two ways; in block
-comment form as follows:
+Members and variables can be documented in one of two ways; in block comment
form:
-<pre>
- /**
- A brief description of the member/variable.
-
- A complete description of the member/variable.
- */
- int my_variable_;
+<pre class='command'>
+/**
+ A brief doxygen description of the member/variable.
+
+ A complete description of the member/variable.
+ More text goes here..
+*/
+int my_variable_;
</pre>
-<p>or in the preferred form as in-line comments as follows:
+or in the preferred form as in-line comments as follows:
-<pre>
- int my_variable1_; /**< A brief description of the member/variable. */
- int my_variable2_; ///< A brief description of member/variable
+<pre class='command'>
+int my_variable1_; ///< C++ file's brief doxygen description of the
member/variable
+int my_variable2_; /**< C file's brief doxygen description of the
member/variable */
</pre>
<h2>Methodology, Algorithms, Etc.</h2>
@@ -1202,10 +1385,43 @@
#endif
</tt></pre>
</ol>
-
+<li class='new'><a name="FLTK_ABI_VERSION">FLTK_ABI_VERSION</a> is used to
allow developers
+ to implement ABI breaking code in <a href="#PATCH_RELEASES">Patch
Releases</a>.
+ Normally unset, can be set by users or devs in FL/Enumerations.H to enable
+ ABI breaking features for testing or use by end users in static builds of
FLTK.
+ <p>
+ When set, the variable's value is expected to be the integer
representation
+ of the FLTK version number, where the Minor and Patch numbers are padded to
+ 2 digits to allow for numbers 1 thru 99, e.g.
+ <pre class='command'>
+ #define FLTK_ABI_VERSION 10302 // FLTK version 1.3.2
+ ..'1' is the major version (no padding; avoids octal issues)
+ ..'03' is the minor version (2 digit padding)
+ ..'02' is the patch version (2 digit padding)
+ </pre>
+ ABI breaking features are by default '#ifdef'ed out with this variable
+ during patch releases, and are merged in by developers during the next
+ <a href="#MINOR_RELEASES">Minor Release</a>.
+ <p>
+ Example: if the current patch release is 1.3.1, and the developer adds an
+ ABI-breaking fix to what will be the next 1.3.2 release, then the addition
+ would be implemented as:
+ <pre class='command'>
+ #if FLTK_ABI_VERSION >= 10302 // FLTK 1.3.2, the <u>next</u> patch
release #
+ ... new ABI breaking code ...
+ #else
+ ... old non-ABI breaking (default builds) ...
+ #endif</pre>
+ This variable solves several issues:
+ <ul type=disc>
+ <li> Allows ABI breaking code to be implemented at any time by
developers.</li>
+ <li> Gets fixes into SVN sooner, so users can see, test and access
it.</li>
+ <li> Testing ABI features during Patch Releases increases the stability
of Minor Releases.</li>
+ <li> Prevents devs having to defer ABI breaking code to the small
window of time preceding Minor Releases.</li>
+ </ul>
+ </li>
</ul>
-
<h2>Miscellaneous</h2>
When using <tt>switch</tt> - <tt>case</tt> statements, and your
@@ -1648,8 +1864,52 @@
libraries after installation since the symbol table is
invalidated when the library is copied on some platforms.
+<hr>
+
+<h2><a name="DEVELOPER_REFERENCE">Developer References</a></h2>
+
+<ul class='new'>
+
+ <h3><a name='DEVELOPER_REFERENCE_COMMENT_STYLE'>Comment Style</a></h3>
+ Developers for 1.3 settled on the /** .. */ format for these reasons:
+ <pre>
+ erco 3/13/09:
+ I do like when (*)s run down left margin of all comments; easier to
differentiate comments
+ from code in large doc blocks.
+ matt 3/14/09:
+ Yes, same here. I usually align them in the second column.
+ erco 3/15/09:
+ Duncan doesn't like (*)s down the left because it complicates paragraph
reformatting.. passing that on.
+ erco 3/15/09:
+ Albrecht says this was already discussed and decision was *no stars*
down the left,
+ so I modified the examples here to follow this rule.
+ erco 3/15/09:
+ Note: fltk2 uses QT /*! style comments, whereas fltk1 uses /** as
described above.
+ Should standard reflect this?
+ erco 07/18/10:
+ We seem to be going with /** style comments, no (*)s running down left
margin (as per Duncan's sugg).
+ </pre>
+
+ <h3><a name='DEVELOPER_REFERENCE_GENERAL'>General Developer
Recommendations</a></h3>
+ Many of the notes in this section are from Fabien's TODO.doc, and seem
consistent with the
+ actual fltk docs during the 1.1.x-to-1.3.x doxygenification transition.
+
+</ul>
+
+ <!-- vertical white to allow HREF's to get here with correct scroll position
-->
+ <br><br><br> <br><br><br> <br><br><br>
+ <br><br><br> <br><br><br> <br><br><br>
+ <br><br><br> <br><br><br> <br><br><br>
+
+ <center> ** This space intentionally left blank ** </center>
+
+ <br><br><br> <br><br><br> <br><br><br>
+ <br><br><br> <br><br><br> <br><br><br>
+ <br><br><br> <br><br><br> <br><br><br>
+
</div>
+
<?php
html_footer();
Modified: trunk/fltk.css
===================================================================
--- trunk/fltk.css 2012-02-25 17:37:26 UTC (rev 659)
+++ trunk/fltk.css 2012-03-05 02:59:53 UTC (rev 660)
@@ -124,3 +124,28 @@
.invalid {
color: red;
}
+
+.new {
+ color: #880000;
+ font-decoration: none;
+}
+
+table.simple-table
+{
+ border:2px solid black;
+ border-collapse:collapse;
+}
+
+table.simple-table th
+{
+ border:2px solid black;
+ padding: 3px;
+}
+
+table.simple-table td
+{
+ border:2px solid black;
+ padding: 3px;
+}
+
+
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
