Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Em Thu, 16 Dec 2021 16:12:15 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Tomasz Warniełło <tomasz.warniello@gmail.com> writes:
> 
> > The only change in the script execution flow is the replacement
> > of the 'usage' function with the native core Perl 'pod2usage'.
> >
> > This entails:
> > - an overall documentation restructuring
> > - addition of a synopsis
> >
> > Otherwise my intervention is minimal:
> > - a few tiny language, formatting and spacing corrections
> > - a few missing bits added in the command syntax description
> > - adding subsections in the "FORMAT OF COMMENTS" section
> > - alphabetical sorting within OPTIONS subections  
> 
> So I think that this is generally a good thing, but I do have some
> quibbles.  Starting with the above, which is a pretty clear violation of
> the "each patch does one thing" rule.  Please separate out your changes
> into separate patches so that they are more easily reviewed.

I almost did that in the past, but due to a different rationale ;-)

Besides the points that Jonathan already mentioned, I'd like to add
one additional request...

Pod is very useful when associated with Getopt, e. g.:

	use Getopt::Long;
	use Pod::Usage;

In a similar way to scripts/get_abi.pl (and scripts/get_feat.pl).

This simplifies a lot the parameter handling, as it would
be like:

	GetOptions(
		"debug=i" => \$debug,
		"enable-lineno" => \$enable_lineno,
		"rst-source!" => \$description_is_rst,
		"dir=s" => \$prefix,
		'help|?' => \$help,
		"show-hints" => \$hint,
		"search-string=s" => \$search_string,
		man => \$man
	) or pod2usage(2);

This would make easier to maintain the parameters and the associated
summary help and man-like help. An additional advantage of using Getopt
is that the parameters can be added before or after the file name.

IMO, the best would be to add a patch at the version 2 of this series
in order to use GetOpt too.

> A few other things below...
> 
> > Finally, the TODO stub evolves into a section:
> > - perldoc request removed
> > - undocumented options added
> >
> > Run `kernel-doc -h` to see the full doc.
> >
> > The TODO suggestion is ancient, thus I can't address its author with
> > a "Suggested-by" tag.
> >
> > Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> > ---
> >  scripts/kernel-doc | 613 ++++++++++++++++++++++++++++++---------------
> >  1 file changed, 413 insertions(+), 200 deletions(-)
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index 3106b7536b89..00c0c7f5ff58 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -4,46 +4,33 @@
> >  use warnings;
> >  use strict;

I would also add:

	BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }

at the final version, in order to produce a better output.

Regards,
Mauro


Thanks,
Mauro