linux-kernel - Re: [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87wnhu2yfj.fsf@meer.lwn.net>
Date:   Wed, 16 Feb 2022 16:18:08 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Tomasz Warniełło <tomasz.warniello@...il.com>
Cc:     Tomasz Warniełło <tomasz.warniello@...il.com>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section

My first comment is that the changelogs need work.  A changelog on a
patch should say what *that patch* is doing and, more importantly, why.  
Neither of those are present here.

Tomasz Warniełło <tomasz.warniello@...il.com> writes:

This information, to the extent that it's needed, should be a part of
the series description in part 0.

> You can see the POD with:
>
> $ perldoc scripts/kernel-doc
>
> * Transform documentation into POD (1/15)
> = Series explanation =
>
> This series transforms the free-form general comments - mainly the usage
> instructions and the meta information - into the standard Perl
> documentation format. Some of the original text is reduced out.
>
> The transformation includes language, paragraphing and editorial
> corrections.
>
> The only change in the script execution flow is the replacement of the
> 'usage' function with the native core Perl 'pod2usage'.
>
> The TODO suggestion to write POD found in the script is ancient, thus
> I can't address its author with a "Suggested-by" tag.
>
> The process consists of 15 steps.
>
> 1) Add the NAME section
> 2) Add the SYNOPSIS section
> 3) Relink argument parsing error handling to pod2usage
>
> The following subseries is disfunctional before its last part.
>
> 4) Translate the DESCRIPTION section
> 5) Translate the "Output format selection" subsection of OPTIONS
> 6) Translate the "Output format selection modifier" subsection of OPTIONS
> 7) Translate the "Output selection" subsection of OPTIONS
> 8) Translate the "Output selection modifiers" subsection of OPTIONS
> 9) Translate the "Other parameters" subsection of OPTIONS
> 10) Replace the usage function
>
> Here the DESCRIPTION and OPTIONS subseries is finished. The -h and -help
> parameters are handled by POD now.
>
> 11) Remove the "format of comments" comment block
> 12) Archive the pre-git museum
> 13) License cleanup
> 14) Refresh the copyright lines
> 15) Move the TODOs
>
> Signed-off-by: Tomasz Warniełło <tomasz.warniello@...il.com>
> ---
>  scripts/kernel-doc | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 3106b7536b89..46d3e779bf5d 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -16,6 +16,12 @@ use strict;
>  ## This software falls under the GNU General Public License.     ##
>  ## Please read the COPYING file for more information             ##
>  
> +=head1 NAME
> +
> +kernel-doc - Print formatted kernel documentation to stdout
> +
> +=cut
> +

So, we do like patches to be granular and do only one thing, but this
may be taking it a bit too far.  It could well be combined with patch 2,
for example, which is just adding another section.

Meanwhile, I'd describe its role is something like "extract and format
documentation from the kernel source".

Thanks,

jon