* The longer description can have multiple paragraphs.
*/
-The first line, with the short description, must be on a single line.
+The short description following the subject can span multiple lines
+and ends with an @argument description, an empty line or the end of
+the comment block.
The @argument descriptions must begin on the very next line following
this opening short function description line, with no intervening
* (section header: (section description)? )*
(*)?*/
-The short function description ***cannot be multiline***, but the other
-descriptions can be (and they can contain blank lines). If you continue
-that initial short description onto a second line, that second line will
-appear further down at the beginning of the description section, which is
-almost certainly not what you had in mind.
+All "description" text can span multiple lines, although the
+function_name & its short description are traditionally on a single line.
+Description text may also contain blank lines (i.e., lines that contain
+only a "*").
+
+"section header:" names must be unique per function (or struct,
+union, typedef, enum).
Avoid putting a spurious blank line after the function name, or else the
description will be repeated!
Inside a struct description, you can use the "private:" and "public:"
comment tags. Structure fields that are inside a "private:" area
-are not listed in the generated output documentation.
+are not listed in the generated output documentation. The "private:"
+and "public:" tags must begin immediately following a "/*" comment
+marker. They may optionally include comments between the ":" and the
+ending "*/" marker.
Example:
struct my_struct {
int a;
int b;
-/* private: */
+/* private: internal use only */
int c;
};