Re: [PATCH v2 7/8] docs: add a script to check sysctl docs

[Jonathan Corbet]

On Tue, 18 Feb 2020 13:59:22 +0100
Stephen Kitt <steve@xxxxxxx> wrote:

> This script allows sysctl documentation to be checked against the
> kernel source code, to identify missing or obsolete entries. Running
> it against 5.5 shows for example that sysctl/kernel.rst has two
> obsolete entries and is missing 52 entries.
> 
> Signed-off-by: Stephen Kitt <steve@xxxxxxx>

So I like the idea here, but I have a couple of nits and one larger
thought...
> ---
>  Documentation/admin-guide/sysctl/kernel.rst |   3 +
>  scripts/check-sysctl-docs                   | 181 ++++++++++++++++++++
>  2 files changed, 184 insertions(+)
>  create mode 100755 scripts/check-sysctl-docs
> 
> diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst
> index a67c218c4066..3d21e076aea4 100644
> --- a/Documentation/admin-guide/sysctl/kernel.rst
> +++ b/Documentation/admin-guide/sysctl/kernel.rst
> @@ -2,6 +2,9 @@
>  Documentation for /proc/sys/kernel/
>  ===================================
>  
> +.. See scripts/check-sysctl-docs to keep this up to date
> +
> +
>  Copyright (c) 1998, 1999,  Rik van Riel <riel@xxxxxxxxxxxx>
>  
>  Copyright (c) 2009,        Shen Feng<shen@xxxxxxxxxxxxxx>
> diff --git a/scripts/check-sysctl-docs b/scripts/check-sysctl-docs
> new file mode 100755
> index 000000000000..b3b47c188a2d
> --- /dev/null
> +++ b/scripts/check-sysctl-docs
> @@ -0,0 +1,181 @@
> +#!/usr/bin/gawk -f
> +# SPDX-License-Identifier: GPL-2.0-only

By Documentation/process/license-rules.rst, that should be "GPL-2.0"; the
absence of a "+" means "only".

> +# Script to check sysctl documentation against source files
> +#
> +# Copyright  2020 Stephen Kitt

Some people object to the introduction of unnecessary non-ASCII text, and
this one would count; can we take the  symbol out?

Now for the bigger thought...  I wonder if what we really want to do is
to adopt some form of the kerneldoc format for sysctl knobs?  That would
allow the documentation to be placed in the source right next to the
table entries, which might, in the optimistic world I inhabit, help
developers to keep them up to date.

That, of course, is more work than what you've done; until somebody feels
inspired to do that work I'll happily accept a tweaked version of this
script.  But one can always dream...

Thanks,

jon