hacking: add a section on preprocessor conventions

* doc/hacking.html.in (preprocessor): New section to document
recently-discussed style issues.

Signed-off-by: Eric Blake <eblake@redhat.com>

diff --git a/HACKING b/HACKING
index b6f63ddac174189deb7e7b055558cd6f99cdeba2..9ee87c1061cbb11585fe75e4cff2842dcc2c4951 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -102,6 +102,20 @@ Usually they're in macro definitions or strings, and should be converted
 anyhow.
 
 
+Preprocessor
+============
+For variadic macros, stick with C99 syntax:
+
+#define vshPrint(_ctl, ...)   fprintf(stdout, __VA_ARGS__)
+
+Use parenthesis when checking if a macro is defined, and use
+indentation to track nesting:
+
+#if defined(HAVE_POSIX_FALLOCATE) && !defined(HAVE_FALLOCATE)
+# define fallocate(a,ignored,b,c) posix_fallocate(a,b,c)
+#endif
+
+
 C types
 =======
 Use the right type.

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 15029ac5348bf9caa085efa1600f59728e3565e7..8771c54f975558543ca753f9cc6ef6d3ffdcbaf9 100644 (file)
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -124,6 +124,25 @@
     </p>
 
 
+    <h2><a href="types">Preprocessor</a></h2>
+
+    <p>
+      For variadic macros, stick with C99 syntax:
+  <pre>
+  #define vshPrint(_ctl, ...) fprintf(stdout, __VA_ARGS__)
+  </pre>
+    </p>
+
+    <p>Use parenthesis when checking if a macro is defined, and use
+    indentation to track nesting:
+
+  <pre>
+  #if defined(HAVE_POSIX_FALLOCATE) &amp;&amp; !defined(HAVE_FALLOCATE)
+  # define fallocate(a,ignored,b,c) posix_fallocate(a,b,c)
+  #endif
+  </pre>
+    </p>
+
     <h2><a href="types">C types</a></h2>
 
     <p>
@@ -405,7 +424,7 @@
   #include &lt;limits.h&gt;
 
   #if HAVE_NUMACTL                Some system includes aren't supported
-  #include &lt;numa.h&gt;               everywhere so need these #if defences.
+  # include &lt;numa.h&gt;               everywhere so need these #if defences.
   #endif
 
   #include "internal.h"           Include this first, after system includes.