Em Thu, 16 Dec 2021 16:12:15 -0700
Jonathan Corbet <corbet@xxxxxxx> escreveu:
> Tomasz Warniełło <tomasz.warniello@xxxxxxxxx> 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@xxxxxxxxx>
> > ---
> > 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
