svn commit: r275961 - head/sys/arm/conf

[Bruce Evans]

On Sun, 21 Dec 2014, Ian Lepore wrote:

> On Sun, 2014-12-21 at 08:07 +0000, Alexey Dokuchaev wrote:
>> On Sat, Dec 20, 2014 at 06:15:24PM +0000, Andrew Turner wrote:
>>> Log:
>>>   Clean up to use the standard style of "options \t" and "device\t\t"
>>>
>>>  options  	HZ=500			# Scheduling quantum is 2 milliseconds.
>>> [...]
>>> -options  	KDB			# Enable kernel debugger support.
>>> +options 	KDB			# Enable kernel debugger support.
>>>  # For minimum debugger support use KDB_TRACE, for interactive use DDB.
>>> -#options  	KDB_TRACE		# Print a stack trace for a panic.
>>> -options  	DDB			# Support DDB.
>>> +#options 	KDB_TRACE		# Print a stack trace for a panic.
>>> +options 	DDB			# Support DDB.
>>>  # For full debugger support use this instead:
>>> -#options  	GDB			# Support remote GDB.
>>> +#options 	GDB			# Support remote GDB.
>>> [...]
>>
>> It also would be nice if we removed trailing dots in comments one day,
>> preferreably across all config files we have in the tree.
>
> Why?  I thought our rule about comments is that they're complete
> sentences, punctuated as such.

That rule is for C source code and doesn't apply to comments to the
right of code even there.

The rule for options files is to never terminate options or device lines
with periods.  This rule was broken in only 1 places in the RELENG_4
i386 GENERIC (for the tun device).  Also, it is not even broken for 2
options:

X options 	AHC_REG_PRETTY_PRINT	# Print register bitfields in debug
X 					# output.  Adds ~128k to driver.
X options 	AHD_REG_PRETTY_PRINT	# Print register bitfields in debug 
X 					# output.  Adds ~215k to driver.

These lines break many other rules:
- that comments to the right of code actually be at the right of code and
   not spread across multiple lines
- that man pages not be written in comments.  Especially ones at the
   right of code where there is less space.
- various anti-verbosity rules stricter than the previous one.

The i386 GENERIC is still relatively clean, but the breakage of this rule
has expanded to include 2 GEOM options, PRINTR_BUFR_SIZE (ick; its
description also breaks the line length limit rule), most KDB/DDB options,
aic, ie, an, bwi, bwn, ipw, ipi, iwi, iwn, malo, mwl, ral, wi, wl and wpi.
aic, ie, an, bwi, iwi, ral and wi also break the line length limit rule.

> Of course, I also thought we had a rule that 'device' and 'options' in
> kernel config is always followed by two spaces then a tab, so that you
> can comment out lines without ruining the indent, and apparently that's
> not true either (and I have no idea where I got that notion).

The rule for `options' is that it is always followed by _one_ space and
a tab.  This rule os currently followed by all options lines in i386
GENERIC.

`device' lines used to follow Rafferty's rules.  They used to be mostly
formatted with `device' followed by a single tab, and comments to the
right of them lined up in subsections but globally random.  This has
been cleaned up a bit, at the cost of breaking the line length limit
rule in many places.  `device' is now consistently followed by _two_
tabs in i386 GENERIC, and comments are consistently lined up starting
in column 40 for both `options' and `device' lines.  The fancy space+tab
rule is less needed for `device' lines, since a single comment character
can be prefixed without breaking the formatting.  I use this to
distinguish local modifications:
- GENERIC shouldn't have any commented-out device lines, but i386 GENERIC
   actually has about 10 (formatted with a single comment character so as
   not to break the formatting)
- local modifications comment out device lines using '# '.  This breaks
   the formatting.

NOTES files provide many more bad examples than i386 GENERIC.

Bruce