Clarify style(9) WRT comments following #endif, #else.

The closing comment is required only for long conditionally defined
code sections, with the exception of lint cases.  Attempt to document
also the logic for using '!' before the SOMETIMESSOMETHGINGHERE.
The goal of these comments is to make complex cases more
comprehensible, not to require them in all cases.  The rules here are
derived from behavior used in 90+% of the kernel source code.

Reviewed by and discussed with:	jhb, bde, mike

1 files changed, 63 insertions, 1 deletions

diff --git a/share/man/man9/style.9 b/share/man/man9/style.9
index 2627e85..e5e2061 100644
--- a/share/man/man9/style.9
+++ b/share/man/man9/style.9
@@ -82,7 +82,7 @@ in front of foreign VCS IDs if the file is renamed.
 #if 0
 #ifndef lint
 static char sccsid[] = "@(#)style	1.14 (Berkeley) 4/28/95";
-#endif /* not lint */
+#endif /* !lint */
 #endif
 
 #include <sys/cdefs.h>
@@ -180,6 +180,68 @@ for pretty-printers and editors.
 } while (0)
 .Ed
 .Pp
+When code blocks are conditionally defined using
+.Ic #ifdef
+or
+.Ic #if ,
+a comment may be added following the matching
+.Ic #endif
+or
+.Ic #else
+to permit the reader to easily discern where conditionally defined code
+regions end.
+This comment should be used only for (subjectively) long regions, regions
+greater than 20 lines, or where a series of nested
+.Ic #ifdef 's
+may be confusing to the reader.
+Exceptions may be made for cases where code is contionally undefined for
+the purposes of lint, even though the undefined region may be small.
+The comment shall be seperated from the
+.Ic #endif
+or
+.Ic #else
+by a single space.
+For short conditionally defined regions, a closing comment should not be
+used.
+.Pp
+The comment for
+.Ic #endif
+should match the expression used in
+.Ic #if
+or
+.Ic #ifdef .
+The comment for
+.Ic #else
+should be the inverse of the expression used in the previous
+.Ic #if
+or
+.Ic #elsif .
+In the comments, the subexpression
+.Dq Li defined(FOO)
+is abbreviated as
+.Dq Li FOO .
+For the purposes of comments,
+.Dq Ic #ifndef Li FOO
+is treated as
+.Dq Ic #if Li !defined(FOO) .
+.Bd -literal
+#ifdef KTRACE
+#include <sys/ktrace.h>
+#endif
+
+#ifdef COMPAT_43
+/* A long block here, or other conditional code. */
+#else /* !COMPAT_43 */
+/* Or here. */
+#endif /* COMPAT_43 */
+
+#ifndef COMPAT_43
+/* Yet another long block here, or other conditional code. */
+#else /* COMPAT_43 */
+/* Or here. */
+#endif /* !COMPAT_43*/
+.Ed
+.Pp
 Enumeration values are all uppercase.
 .Bd -literal
 enum enumtype { ONE, TWO } et;