From owner-svn-src-head@FreeBSD.ORG Mon Dec 22 00:30:16 2014 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 0B6E8E7A; Mon, 22 Dec 2014 00:30:16 +0000 (UTC) Received: from mail108.syd.optusnet.com.au (mail108.syd.optusnet.com.au [211.29.132.59]) by mx1.freebsd.org (Postfix) with ESMTP id 8F7833BFB; Mon, 22 Dec 2014 00:30:15 +0000 (UTC) Received: from c122-106-147-133.carlnfd1.nsw.optusnet.com.au (c122-106-147-133.carlnfd1.nsw.optusnet.com.au [122.106.147.133]) by mail108.syd.optusnet.com.au (Postfix) with ESMTPS id 488E21A529E; Mon, 22 Dec 2014 11:30:06 +1100 (AEDT) Date: Mon, 22 Dec 2014 11:30:05 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Ian Lepore Subject: Re: svn commit: r275961 - head/sys/arm/conf In-Reply-To: <1419180311.1018.66.camel@freebsd.org> Message-ID: <20141222105500.E911@besplex.bde.org> References: <201412201815.sBKIFOSq060122@svn.freebsd.org> <20141221080739.GB27290@FreeBSD.org> <1419180311.1018.66.camel@freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.1 cv=R8o6R7hX c=1 sm=1 tr=0 a=7NqvjVvQucbO2RlWB8PEog==:117 a=PO7r1zJSAAAA:8 a=kj9zAlcOel0A:10 a=JzwRw_2MAAAA:8 a=pS3UQe8eFl3rWVsDjHcA:9 a=G8QlLWlbfa_le2eK:21 a=0ysKVROebSIKcJAp:21 a=CjuIK1q_8ugA:10 Cc: Andrew Turner , svn-src-head@freebsd.org, Alexey Dokuchaev , src-committers@freebsd.org, svn-src-all@freebsd.org X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 22 Dec 2014 00:30:16 -0000 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