Re: [RFC] Proposal to relax warnings of htmldocs

[Jonathan Corbet <corbet@lwn.net>]

Carlos Bilbao <carlos.bilbao@amd.com> writes:

>> ...other than fixing the actual problems? :)
>
> I'm happy to fix as many as I can, but there are obstacles e.g. some things
> lack documentation, such as undocumented fields in structures with names
> that nobody but their creator could decipher. Also, that won't solve the
> underlying warning display problem (which maybe it's W!=1, as noted by
> Matthew.

I *did* put a smiley on that...

>>> I suggest for the command `make htmldocs` to
>>> only display, by default, warnings directly related to the changes being
>>> made, unless explicitly requested otherwisee.
>>>
>>> I'm thinking we could do this, for example, by making hmtldocs a two-step
>>> process: First running htmldocs as usual but with warnings disabled, and
>>> then generating docs again but only for the new files (see $git diff
>>> --name-only HEAD), with warnings active but limited to the scope of the
>>> changes made.
>> 
>> A normal build should just generate warnings for files that have
>> changed (since the last build).  Does that not do what you want?
>
> That's not the behavior I see on my system, when I run `make htmldocs` I
> see many warnings from other places.It floods my screen. The default
> behavior appears to change between configurations and compilers.

Warnings that are generated at output time, such as broken references,
will come out every time.  Those generated during the read phase are
generally limited to what has been changed.  I rely on that pretty
heavily to do incremental builds when applying patches.  If you're doing
a full rebuild after changing one file, something strange is happening.

Thanks,

jon