and any comment so marked must be in kernel-doc format. Do not use
"/**" to be begin a comment block unless the comment block contains
kernel-doc formatted comments. The closing comment marker for
-kernel-doc comments can be either "*/" or "**/".
+kernel-doc comments can be either "*/" or "**/", but "*/" is
+preferred in the Linux kernel tree.
Kernel-doc comments should be placed just before the function
or data structure being described.
* comment lines.
*
* 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
* perhaps with more lines and words.
*
* Longer description of this structure.
- **/
+ */
The kernel-doc function comments describe each parameter to the
function, in order, with the @name lines.
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;
};