Messages in this thread Patch in this message | | | Date | Mon, 3 Jan 2022 21:40:35 +0100 | From | Mauro Carvalho Chehab <> | Subject | Re: [PATCH] scripts: kernel-doc: transform documentation into POD |
| |
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
| |