[PATCH] scripts/kernel-doc: Do not track section counter across processed files

[PATCH] scripts/kernel-doc: Do not track section counter across processed files

[Chen-Yu Tsai]

The section counter tracks how many sections of kernel-doc were added.
The only real use of the counter value is to check if anything was
actually supposed to be output and give a warning is nothing is
available.

The current logic of remembering the initial value and then resetting
the value then when processing each file means that if a file has the
same number of sections as the previously processed one, a warning is
incorrectly given.

Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2")
Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
---
Found this while improving and checking the kernel docs for the
regulator core.

 scripts/kernel-doc | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 2791f8195203..c608820f0bf5 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2322,7 +2322,6 @@ sub process_inline($$) {
 
 sub process_file($) {
     my $file;
-    my $initial_section_counter = $section_counter;
     my ($orig_file) = @_;
 
     $file = map_filename($orig_file);
@@ -2360,8 +2359,7 @@ sub process_file($) {
     }
 
     # Make sure we got something interesting.
-    if ($initial_section_counter == $section_counter && $
-        output_mode ne "none") {
+    if (!$section_counter && $output_mode ne "none") {
         if ($output_selection == OUTPUT_INCLUDE) {
             emit_warning("${file}:1", "'$_' not found\n")
                 for keys %function_table;
-- 
2.47.0.rc0.187.ge670bccf7e-goog

Re: [PATCH] scripts/kernel-doc: Do not track section counter across processed files

[Jonathan Corbet]

Chen-Yu Tsai <wenst@chromium.org> writes:

> The section counter tracks how many sections of kernel-doc were added.
> The only real use of the counter value is to check if anything was
> actually supposed to be output and give a warning is nothing is
> available.
>
> The current logic of remembering the initial value and then resetting
> the value then when processing each file means that if a file has the
> same number of sections as the previously processed one, a warning is
> incorrectly given.
>
> Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2")
> Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
> ---
> Found this while improving and checking the kernel docs for the
> regulator core.
>
>  scripts/kernel-doc | 4 +---
>  1 file changed, 1 insertion(+), 3 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 2791f8195203..c608820f0bf5 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -2322,7 +2322,6 @@ sub process_inline($$) {
>  
>  sub process_file($) {
>      my $file;
> -    my $initial_section_counter = $section_counter;
>      my ($orig_file) = @_;
>  
>      $file = map_filename($orig_file);
> @@ -2360,8 +2359,7 @@ sub process_file($) {
>      }
>  
>      # Make sure we got something interesting.
> -    if ($initial_section_counter == $section_counter && $
> -        output_mode ne "none") {
> +    if (!$section_counter && $output_mode ne "none") {
>          if ($output_selection == OUTPUT_INCLUDE) {
>              emit_warning("${file}:1", "'$_' not found\n")
>                  for keys %function_table;

So I am curious, have you actually seen a spurious warning from this?  A
normal build does not emit any here.

The current logic is indeed screwy, I'll apply this fix.  But
$section_counter kind of seems like a holdover from the docbook days and
maybe isn't needed at all anymore?

Thanks,

jon

Re: [PATCH] scripts/kernel-doc: Do not track section counter across processed files

[Chen-Yu Tsai]

On Tue, Oct 15, 2024 at 2:22 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Chen-Yu Tsai <wenst@chromium.org> writes:
>
> > The section counter tracks how many sections of kernel-doc were added.
> > The only real use of the counter value is to check if anything was
> > actually supposed to be output and give a warning is nothing is
> > available.
> >
> > The current logic of remembering the initial value and then resetting
> > the value then when processing each file means that if a file has the
> > same number of sections as the previously processed one, a warning is
> > incorrectly given.
> >
> > Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2")
> > Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
> > ---
> > Found this while improving and checking the kernel docs for the
> > regulator core.
> >
> >  scripts/kernel-doc | 4 +---
> >  1 file changed, 1 insertion(+), 3 deletions(-)
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index 2791f8195203..c608820f0bf5 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -2322,7 +2322,6 @@ sub process_inline($$) {
> >
> >  sub process_file($) {
> >      my $file;
> > -    my $initial_section_counter = $section_counter;
> >      my ($orig_file) = @_;
> >
> >      $file = map_filename($orig_file);
> > @@ -2360,8 +2359,7 @@ sub process_file($) {
> >      }
> >
> >      # Make sure we got something interesting.
> > -    if ($initial_section_counter == $section_counter && $
> > -        output_mode ne "none") {
> > +    if (!$section_counter && $output_mode ne "none") {
> >          if ($output_selection == OUTPUT_INCLUDE) {
> >              emit_warning("${file}:1", "'$_' not found\n")
> >                  for keys %function_table;
>
> So I am curious, have you actually seen a spurious warning from this?  A
> normal build does not emit any here.

Yes indeed. I was cleaning up some kernel doc sections for the regulator
core and running both files through the tool together. At some point I
was getting the warning and not getting any output from the second
input file.

> The current logic is indeed screwy, I'll apply this fix.  But
> $section_counter kind of seems like a holdover from the docbook days and
> maybe isn't needed at all anymore?

I've lost most of the context around this, but AFAIK if we don't care
about not having anything to output and can drop the warning, then
$section_counter could be dropped together.


ChenYu

> Thanks,
>
> jon