Date: Fri, 29 Jul 2016 08:42:33 +1000 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Konstantin Belousov <kib@freebsd.org> Cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r303446 - head/sys/vm Message-ID: <20160729075631.L944@besplex.bde.org> In-Reply-To: <201607281549.u6SFnqQK016697@repo.freebsd.org> References: <201607281549.u6SFnqQK016697@repo.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 28 Jul 2016, Konstantin Belousov wrote: > Log: > Fix style and typo. > > Modified: head/sys/vm/swap_pager.c > ============================================================================== > --- head/sys/vm/swap_pager.c Thu Jul 28 15:33:19 2016 (r303445) > +++ head/sys/vm/swap_pager.c Thu Jul 28 15:49:51 2016 (r303446) > @@ -390,8 +390,8 @@ static int dmmax; > static int nswap_lowat = 128; /* in pages, swap_pager_almost_full warn */ > static int nswap_hiwat = 512; /* in pages, swap_pager_almost_full warn */ > > -SYSCTL_INT(_vm, OID_AUTO, dmmax, > - CTLFLAG_RD, &dmmax, 0, "Maximum size of a swap block"); > +SYSCTL_INT(_vm, OID_AUTO, dmmax, CTLFLAG_RD, &dmmax, 0, > + "Maximum size of a swap block"); This fixes the indentation, but only moves the style bug in the long-line splitting. The first line of a SYSCTL_<SCALAR> is conventionally split after CTFLAG* if this would not leave it too long. This puts the variable name in an easier-to-read place and inhibits verbose descriptions. The line splitting for the first is now consistently broken for all nearby sysctls. There are many style bugs in the descriptions in neary sysctls: - some are terminated by a "." - most are too long, using poor wording to make them longer. Some say "amount", and some say "size". Both of these words are almost redundant and do little to describe the units. Apparently, sizes are in bytes. Some of the amounts are apparently also in bytes, but swap_maxpages is dimensionless. Its name tells you more in half the space as it description "Maximum amount of swap supported". - the description for vm.overcommit is especially bad. It takes multiple sentences with misformatting and a long line with misformatting to refer to the man page for details. Otherwise, it basically says "Enable overcommit". Its only unobvious point is that the man page is tuning(7) and not vm(7nonexistent). I haven't found anuthing better than zgrep -r in /usr/shar/man for finding man page references. vm.overcommit is also badly described in getrlimit(2). This adds to the verboseness using "Please see" and expanding "details" to "complete description of". sysctl -da | grep '\.$' | wc on freefall finds only 102 descriptions with a trailing "." in 4115 lines. The pattern ": [^A-Z] matches 1580 lines. 1410 of the 1580 uncapitalized lines have a leading 'dev' and most of these style bugs are in auto-generated spam. The spam gives useless descriptions like %parent: "parent device". IIRC, the strings for this spam are not duplicated in the kernel, so they don't waste space there, but this means that they cannot contain any useful context-dependent information. '[Aa]mount' is mercifully unpopular. It matches just 20 lines, mostly near here and in vfs_bio. Bruce Bruce
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20160729075631.L944>