docs/coding: Explain function/struct/union comment conventions

Signed-off-by: Markus Armbruster <armbru@pond.sub.org>

diff --git a/doc/coding b/doc/coding
index 66e9d4f6b674f364cae7b9926b607c5e7d55fe8b..e2e07b5b808da93c89928213b02093ad7f29a5a9 100644 (file)
--- a/doc/coding
+++ b/doc/coding
@@ -170,7 +170,7 @@ above the definition.
 Comments to the right of code should start in column 32 if possible
 (counting from zero).
 
 Comments to the right of code should start in column 32 if possible
 (counting from zero).
 

-Comment lines should be indented exactly like the code the belong to.
+Comment lines should be indented exactly like the code they belong to.

 
 You are encouraged to format multi-line comments like this:
 
 
 You are encouraged to format multi-line comments like this:
 


@@ -193,7 +193,6 @@ Do not use
 
 because they are not portable C89.
 
 
 because they are not portable C89.
 

-

 Conditional compilation
 
 Unless the conditional code is very short, please comment it like
 Conditional compilation
 
 Unless the conditional code is very short, please comment it like


@@ -247,10 +246,35 @@ Comments
 Every file should have a file comment FIXME
 
 Every function should have a function comment that describes what it
 Every file should have a file comment FIXME
 
 Every function should have a function comment that describes what it

-does.  FIXME elaborate.  Writing such comments helps both future
-maintainers and yourself: if it's too hard to write a concise function
-comment, then your function is likely too complicated and could use a
-redesign.
+does, unless it's blatantly obvious.  If the function is longer than a
+few lines, it's almost certainly not obvious.
+
+The function comment should serve as a contract: state the
+preconditions, side effects, return values.  Make sure to cover error
+conditions.
+
+Writing such comments helps both future maintainers and yourself: when
+writing a concise function comment is too hard, then your function is
+likely too complicated and could use a redesign.
+
+Use @param to refer to parameters.  Use func() to refer to functions
+or function-like macros.  Use arr[] to refer to arrays.  This is to
+make the references stand out and to avoid ambiguity.
+
+Example:
+
+    /*
+     * Read update schedule from file @fname.
+     * Put the first @n-1 updates after @t0 into @sched[] in ascending order,
+     * terminated with a zero.
+     * Use @anchor as initial anchor for anchor-relative times.
+     * Return 0 on success, -1 on failure.
+     */
+    int
+    read_schedule(char *fname, time_t sched[], int n, time_t t0, time_t anchor)
+
+When documenting a struct or union, use @member to refer to its
+members.

 
 The existing code has very little useful comments, and it'll likely
 take us years to fix it.  Please don't make it harder than it already
 
 The existing code has very little useful comments, and it'll likely
 take us years to fix it.  Please don't make it harder than it already