client: Unbreak standalone build

[empserver] / doc / coding

diff --git a/doc/coding b/doc/coding
index 66e9d4f6b674f364cae7b9926b607c5e7d55fe8b..afb11e598312437d6037767b9abc3b703992144e 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).
 
-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:
 
@@ -191,9 +191,6 @@ Do not use
 
        // C++/C99 comments
 
-because they are not portable C89.
-
-
 Conditional compilation
 
 Unless the conditional code is very short, please comment it like
@@ -247,10 +244,35 @@ Comments
 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
@@ -338,7 +360,18 @@ it's as relevant as ever:
 Portability
 -----------
 
-FIXME C89, POSIX
+Code for IEEE Std 1003.1-2001 (POSIX.1-2001) with the X/Open System
+Interfaces Extension.  This standard includes ISO/IEC 9899:1999 (C99)
+by reference.
+
+Some systems may have flaws that require work-arounds.  Use Autoconf
+to detect the flaws, and isolate the system-specific code, e.g. by
+providing a replacement function when the system's function is flawed.
+
+Keeping the Windows build working may require extending src/lib/w32/.
+
+Keep the client as portable as practical.  In particular, stick to
+C89.
 
 FIXME sizes, printf formats