svn commit: r303446 - head/sys/vm

[Bruce Evans]

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