Re: more fixups to style(9)

[Chris Pressey <cpressey@xxxxxxxxxxxxxxx>]

Revised version of previous patch.  Includes all the changes mentioned
in it, plus:

Remove 'return' from and add 'do' to the list of keywords which require
a space after them, and clarify that they are control statement
keywords.  Thanks to Jonathan Lemon for pointing this out.

Move the paragraph about how to space casts, sizeof's, and return's
closer to the rest of the paragraphs that talk about spacing.

Exempt . and -> from the 'binary operators require space around them'
rule, and clarify the wording a bit.

Be explicit that the spacing rules for semicolons are essentially the
same as those for commas.

Explain what a 'forever' loop is.

-Chris

Index: style.9
===================================================================
RCS file: /home/dcvs/src/share/man/man9/style.9,v
retrieving revision 1.6
diff -u -r1.6 style.9
--- style.9	25 Feb 2004 17:35:29 -0000	1.6
+++ style.9	26 Feb 2004 15:48:01 -0000
@@ -31,7 +31,7 @@
 .Nd "kernel source file style guide"
 .Sh DESCRIPTION
 This file specifies the preferred style for kernel source files in the
-.Fx
+.Dx
 source tree.
 It is also a guide for preferred userland code style.
 Many of the style rules are implicit in the examples.
@@ -243,7 +243,7 @@
 typedef	const long	baz;		/* This is baz. */
 .Ed
 .Pp
-All functions are prototyped somewhere.
+All functions should be prototyped somewhere.
 .Pp
 Function prototypes for private functions (i.e. functions not used
 elsewhere) go at the top of the first source module.
@@ -251,7 +251,7 @@
 local to one source module should be declared
 .Ic static .
 .Pp
-Functions used from other parts of the kernel are prototyped in the
+Functions used from other parts of the kernel should be prototyped in the
 relevant include file.
 .Pp
 Functions that are used locally in more than one module go into a
@@ -259,11 +259,14 @@
 .Qq Pa extern.h .
 .Pp
 Avoid using the
+.Ic register
+keyword and the
 .Dv __P
 macro from the include file
 .Aq Pa sys/cdefs.h .
-Code in the DragonFly source tree is not
-expected to be K&R compliant.
+Code in the
+.Dx
+source tree is not expected to be K&R compliant.
 .Pp
 Changes to existing files should be consistent with that file's conventions.
 In general, code can be considered
@@ -292,7 +295,7 @@
 to line up:
 .Bd -literal
 static char	*function(int _arg, const char *_arg2, struct foo *_arg3,
-		    struct bar *_arg4);
+			  struct bar *_arg4);
 static void	 usage(void);
 
 /*
@@ -325,7 +328,9 @@
 .Ic switch
 statement that cascade should have a
 .Li FALLTHROUGH
-comment.
+comment, unless they contain no code of their own, as in the
+.Ic case '?'
+element in the example below.
 Numerical arguments should be checked for accuracy.
 Code that cannot be reached should have a
 .Li NOTREACHED
@@ -356,12 +361,18 @@
 	argv += optind;
 .Ed
 .Pp
-Space after keywords
-.Pq Ic if , while , for , return , switch .
+Put a single space after control statement keywords
+.Pq Ic if , do , while , for , switch .
 No braces are
 used for control statements with zero or only a single statement unless that
 statement is more than a single line in which case they are permitted.
-Forever loops are done with
+.Sq Forever
+loops (loops with no test expression, which are only terminated by a
+.Ic break ,
+.Ic return
+or
+.Ic exit
+inside the loop body) are done with
 .Ic for Ns 's ,
 not
 .Ic while Ns 's .
@@ -372,7 +383,7 @@
 		stmt;
 	for (;;) {
 		z = a + really + long + statement + that + needs +
-		    two lines + gets + indented + four + spaces +
+		    two + lines + gets + indented + four + spaces +
 		    on + the + second + and + subsequent + lines;
 	}
 	for (;;) {
@@ -403,7 +414,7 @@
 	while (cnt < 20 && this_variable_name_is_really_far_too_long &&
 	    ep != NULL)
 		z = a + really + long + statement + that + needs +
-		    two lines + gets + indented + four + spaces +
+		    two + lines + gets + indented + four + spaces +
 		    on + the + second + and + subsequent + lines;
 .Ed
 .Pp
@@ -426,25 +437,32 @@
 		stmt;
 .Ed
 .Pp
-No spaces after function names.
-Commas have a space after them.
-No spaces
+Do not put spaces after function names,
 after
 .Ql \&(
 or
 .Ql \&[
-or preceding
-.Ql \&]
+characters, or preceding
+.Ql \&] ,
+.Ql \&) ,
+.Ql \&; ,
 or
-.Ql \&)
+.Ql \&,
 characters.
+But do put a space after commas and semicolons if there is
+further text on the same line.
 .Bd -literal
 	error = function(a1, a2);
 	if (error != 0)
 		exit(error);
 .Ed
 .Pp
-Unary operators do not require spaces, binary operators do.
+Unary operators do not require spaces around them,
+but binary operators (except for
+.Ql \&.
+and
+.Ql \&-> )
+do.
 Do not use parentheses unless they are required for precedence or unless the
 statement is confusing without them.
 Remember that other people may become
@@ -455,6 +473,18 @@
 	k = !(l & FLAGS);
 .Ed
 .Pp
+Casts are not followed by a space.
+Note that
+.Xr indent 1
+does not understand this rule.
+Also, for the purposes of formatting, treat
+.Ic return
+and
+.Ic sizeof
+as functions.  In other words, they are not
+followed by a space, and their single argument
+should be enclosed in parentheses.
+.Pp
 Exits should be 0 on success, or according to the predefined
 values in
 .Xr sysexits 3 .
@@ -497,19 +527,6 @@
 Hiding file declarations in what appears to be a local
 scope is undesirable and will elicit complaints from a good compiler.
 .Pp
-Casts are not followed by a space.
-Note that
-.Xr indent 1
-does not understand this rule.
-.Pp
-For the purposes of formatting, treat
-.Ic return
-and
-.Ic sizeof
-as functions.  In other words, they are not
-followed by a space, and their single argument
-should be enclosed in parentheses.
-.Pp
 .Dv NULL
 is the preferred null pointer constant.
 Use
@@ -567,7 +584,7 @@
 		err(1, (char *)NULL);
 	if ((six = (int *)overflow()) == NULL)
 		errx(1, "number overflowed");
-	return (eight);
+	return(eight);
 }
 .Ed
 .Pp
@@ -582,7 +599,8 @@
 .Ed
 .Pp
 Use ANSI function declarations instead.
-Long parameter lists are wrapped with a normal four space indent.
+Long parameter lists are wrapped so that the first parameter on each line
+lines up with the first parameter on the previous line.
 .Pp
 Variable numbers of arguments should look like this.
 .Bd -literal
@@ -676,7 +694,7 @@
 .Fx
 KNF
 .Nm
-compliant in the repository must not diverge from compliance.
+compliant in the repository should not diverge from compliance.
 .Pp
 Whenever possible, code should be run through a code checker
 (e.g.,