Re: svn commit: r324457 - in head/sys/dev: pccbb pci

[Bruce Evans]

On Mon, 9 Oct 2017, Alan Somers wrote:


Log:
 Remove embedded newlines from sysctl variable descriptions


This doesn't fix the main bug of writing man pages in sysctl descriptions.


Modified: head/sys/dev/pccbb/pccbb_isa.c
==
--- head/sys/dev/pccbb/pccbb_isa.c  Mon Oct  9 22:19:58 2017
(r324456)
+++ head/sys/dev/pccbb/pccbb_isa.c  Mon Oct  9 22:27:38 2017
(r324457)
@@ -75,11 +75,11 @@ static SYSCTL_NODE(_hw, OID_AUTO, pcic, CTLFLAG_RD, 0,

static int isa_intr_mask = EXCA_INT_MASK_ALLOWED;
SYSCTL_INT(_hw_pcic, OID_AUTO, intr_mask, CTLFLAG_RDTUN, _intr_mask, 0,
-"Mask of allowable interrupts for this laptop.  The default is generally\n\
-correct, but some laptops do not route all the IRQ pins to the bridge to\n\
-save wires.  Sometimes you need a more restrictive mask because some of the\n\
-hardware in your laptop may not have a driver so its IRQ might not be\n\
-allocated.");
+"Mask of allowable interrupts for this laptop.  The default is generally"
+" correct, but some laptops do not route all the IRQ pins to the bridge to"
+" save wires.  Sometimes you need a more restrictive mask because some of"
+" the hardware in your laptop may not have a driver so its IRQ might not 
be"
+" allocated.");


More low quality sysctl messages can be found using

sysctl -da | grep -v ': '  # Sloppy check for embedded newlines
sysctl -da | grep '^[^ ]*: [^A-Z]' # Uncapitalized messages
previous | grep '^dev.*%'' # Auto-generated spam for dev tree
sysctl -da | grep '[^.]*\.$'   # Terminating period
sysctl -da | grep '^[^ ]*: .*\..*\.$' # Multiple sentence, term. period
sysctl -da | grep '^[^ ]*: .*\..*[^.]$' # Period, but not terminating
sysctl -da | grep '\.  '   # Normal sentence break
sysctl -da | grep '\. [^.]'# Misformatted sentence break
sysctl -da | grep '..' # (Really 80 dots).  Long lines

Results on freefall:
- 3294 lines of output
- 7 lines with embedded newlines
- 1041 lines with uncapitalized messages
- 637 lines with previous bug auto-generated for dev tree.  Approx 5 lines
  duplicated for each device
- 109 lines with a terminating period but no other periods
- 5 lines with multiple sentences and a terminating period
- 43 lines with a period but not a terminating period.  This is a sloppy
  check for multiple sentences.  It finds a few correct descriptions with
  periods in sysctl names
- 7 lines with normal sentence breaks.  Half for man pages in sysctls in
  this commit
- 17 lines with single-space sentence breaks
- 359 long lines.  Not counting the sysctl name or ': ', only 30 lines are
  too long.  These lines and ones up to about 10 shorter are also too long
  for source lines.

Another type of search finds inconsistent spellings of booleans.  grep -i
for literal "disable" shows 63 lines with the following inconsistencies
and verboseness:
- often "disable" in the description echoes "disable" in the sysctl name.
  But sometimes the sysctl uses "control", or the sysctl name uses "disable"
  but the description uses "disallow"
- when the description uses "Enable/disable" (10 instances), the name uses
  "allow" (2 instances), "use" (1 instance), "enable "(1 instance) or is
  not clearly boolean (6 instances),
- often (in usb cloned descriptions), "Disable is spelled verbosely as
  "Set to disable".  This is still not verbose enough to say that unset
  means "enable" or even "don't disable".  Disable/enable is never used.

For integer variables, there are lots of inconsistences and verboseness
involving "number/number of/num/n".

Bruce
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"

svn commit: r324457 - in head/sys/dev: pccbb pci

[Alan Somers]

Author: asomers
Date: Mon Oct  9 22:27:38 2017
New Revision: 324457
URL: https://svnweb.freebsd.org/changeset/base/324457

Log:
  Remove embedded newlines from sysctl variable descriptions
  
  PR:   112556
  Submitted by: Willem Jan Withagen  (earlier version)
  Reported by:  Willem Jan Withagen, ighi...@gmail.com
  MFC after:3 weeks
  Sponsored by: Spectra Logic Corp

Modified:
  head/sys/dev/pccbb/pccbb_isa.c
  head/sys/dev/pci/pci.c

Modified: head/sys/dev/pccbb/pccbb_isa.c
==
--- head/sys/dev/pccbb/pccbb_isa.c  Mon Oct  9 22:19:58 2017
(r324456)
+++ head/sys/dev/pccbb/pccbb_isa.c  Mon Oct  9 22:27:38 2017
(r324457)
@@ -75,11 +75,11 @@ static SYSCTL_NODE(_hw, OID_AUTO, pcic, CTLFLAG_RD, 0,
 
 static int isa_intr_mask = EXCA_INT_MASK_ALLOWED;
 SYSCTL_INT(_hw_pcic, OID_AUTO, intr_mask, CTLFLAG_RDTUN, _intr_mask, 0,
-"Mask of allowable interrupts for this laptop.  The default is generally\n\
-correct, but some laptops do not route all the IRQ pins to the bridge to\n\
-save wires.  Sometimes you need a more restrictive mask because some of the\n\
-hardware in your laptop may not have a driver so its IRQ might not be\n\
-allocated.");
+"Mask of allowable interrupts for this laptop.  The default is generally"
+" correct, but some laptops do not route all the IRQ pins to the bridge to"
+" save wires.  Sometimes you need a more restrictive mask because some of"
+" the hardware in your laptop may not have a driver so its IRQ might not 
be"
+" allocated.");
 
 /*
  * CL-PD6722's VSENSE method
@@ -90,13 +90,13 @@ allocated.");
 int pcic_pd6722_vsense = 1;
 SYSCTL_INT(_hw_pcic, OID_AUTO, pd6722_vsense, CTLFLAG_RDTUN,
 _pd6722_vsense, 1,
-"Select CL-PD6722's VSENSE method.  VSENSE is used to determine the\n\
-volatage of inserted cards.  The CL-PD6722 has two methods to determine the\n\
-voltage of the card.  0 means assume a 5.0V card and do not check.  1 means\n\
-use the same method that the CL-PD6710 uses (default).  2 means use the\n\
-same method as the CL-PD6729.  2 is documented in the datasheet as being\n\
-the correct way, but 1 seems to give better results on more laptops.");
-
+"Select CL-PD6722's VSENSE method.  VSENSE is used to determine the"
+" voltage of inserted cards.  The CL-PD6722 has two methods to determine"
+" the voltage of the card.  0 means assume a 5.0V card and do not check.  
1"
+" means use the same method that the CL-PD6710 uses (default).  2 means 
use"
+" the same method as the CL-PD6729.  2 is documented in the datasheet as"
+" being the correct way, but 1 seems to give better results on more"
+" laptops."); 
 /*
  * End of configurable parameters.
  */

Modified: head/sys/dev/pci/pci.c
==
--- head/sys/dev/pci/pci.c  Mon Oct  9 22:19:58 2017(r324456)
+++ head/sys/dev/pci/pci.c  Mon Oct  9 22:27:38 2017(r324457)
@@ -321,9 +321,9 @@ SYSCTL_NODE(_hw, OID_AUTO, pci, CTLFLAG_RD, 0, "PCI bu
 static int pci_enable_io_modes = 1;
 SYSCTL_INT(_hw_pci, OID_AUTO, enable_io_modes, CTLFLAG_RWTUN,
 _enable_io_modes, 1,
-"Enable I/O and memory bits in the config register.  Some BIOSes do not\n\
-enable these bits correctly.  We'd like to do this all the time, but there\n\
-are some peripherals that this causes problems with.");
+"Enable I/O and memory bits in the config register.  Some BIOSes do not"
+" enable these bits correctly.  We'd like to do this all the time, but"
+" there are some peripherals that this causes problems with.");
 
 static int pci_do_realloc_bars = 0;
 SYSCTL_INT(_hw_pci, OID_AUTO, realloc_bars, CTLFLAG_RWTUN,
@@ -334,10 +334,10 @@ SYSCTL_INT(_hw_pci, OID_AUTO, realloc_bars, CTLFLAG_RW
 static int pci_do_power_nodriver = 0;
 SYSCTL_INT(_hw_pci, OID_AUTO, do_power_nodriver, CTLFLAG_RWTUN,
 _do_power_nodriver, 0,
-  "Place a function into D3 state when no driver attaches to it.  0 means\n\
-disable.  1 means conservatively place devices into D3 state.  2 means\n\
-aggressively place devices into D3 state.  3 means put absolutely everything\n\
-in D3 state.");
+"Place a function into D3 state when no driver attaches to it.  0 means"
+" disable.  1 means conservatively place devices into D3 state.  2 means"
+" aggressively place devices into D3 state.  3 means put absolutely"
+" everything in D3 state.");
 
 int pci_do_power_resume = 1;
 SYSCTL_INT(_hw_pci, OID_AUTO, do_power_resume, CTLFLAG_RWTUN,
@@ -372,9 +372,10 @@ static int pci_usb_takeover = 1;
 static int pci_usb_takeover = 0;
 #endif
 SYSCTL_INT(_hw_pci, OID_AUTO, usb_early_takeover, CTLFLAG_RDTUN,
-_usb_takeover, 1, "Enable early takeover