Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko <andriy.shevchenko@linux.intel.com>]

On Sat, Nov 08, 2025 at 04:03:15PM -0800, Randy Dunlap wrote:
> On 11/5/25 10:12 AM, Jonathan Corbet wrote:
> > [Heads up to Stephen: this change will add a bunch of warnings that had
> > been dropped before.]
> > Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
> > 
> >> When kernel-doc parses the sections for the documentation some errors
> >> may occur. In many cases the warning is simply stored to the current
> >> "entry" object. However, in the most of such cases this object gets
> >> discarded and there is no way for the output engine to even know about
> >> that. To avoid that, check if the "entry" is going to be discarded and
> >> if there warnings have been collected, issue them to the current logger
> >> as is and then flush the "entry". This fixes the problem that original
> >> Perl implementation doesn't have.
> > 
> > I would really like to redo how some of that logging is done, but that
> > is an exercise for another day.  For now, I have applied this one,
> > thanks.
> 
> I think that this patch is causing a (large) problem.
> 
> With this patch:
> $ make mandocs &>mandocs.out
> 
> Without this patch:
> $ make mandocs &>mandocsnoas.out
> 
> $ wc mandocs.out mandocsnoas.out
>   29544  267393 3229456 mandocs.out
>   10052   95948 1208101 mandocsnoas.out
> 
> so it appears that this patch causes lots of extra output.
> Some of that may be what the patch was trying to do, but
> with this patch, "mandocs.out" above has lots of duplicated
> Warning: lines.
> 
> $ sort mandocs.out | uniq > mandocsuq.out
> $ wc mandocsuq.out
>   18012  167689 1994145 mandocsuq.out
> 
> $ grep -c "^Warning:"  mandocs.out mandocsnoas.out  mandocsuq.out 
> mandocs.out:25273
> mandocsnoas.out:10022
> mandocsuq.out:15252

Yes, that's what Mauro explained, that we may have the dups.

> In mandocs.out above (29544 lines), this line:
> Warning: ../sound/soc/sprd/sprd-mcdt.h:48 struct member 'dma_chan' not described in 'sprd_mcdt_chan'
> 
> is found at lines 7 and 29122.
> 
> So maybe the logging output needs to be repaired sooner
> than later.

Right! But I'm not familiar with this, so I can help only with testing,
and not with real fix development.

-- 
With Best Regards,
Andy Shevchenko