linux-kernel - Re: [PATCH v3 00/17] kernel-doc: add supported to document nested structs/

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20171007103440.35393957@lwn.net>
Date:   Sat, 7 Oct 2017 10:34:40 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Mauro Carvalho Chehab <mchehab@...pensource.com>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Linux Media Mailing List <linux-media@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 00/17] kernel-doc: add supported to document nested
 structs/

On Wed,  4 Oct 2017 08:48:38 -0300
Mauro Carvalho Chehab <mchehab@...pensource.com> wrote:

> Right now, it is not possible to document nested struct and nested unions.
> kernel-doc simply ignore them.
> 
> Add support to document them.

So I've finally found some time to actually look at these; sorry for being
so absent from the discussion.  I plead $EXCUSES...

Some overall impressions:

 - Seems like something we want.
 - I love hacking all the cruft out of kernel-doc; I've been meaning to
   do that for a bit.
 - It would sure be nice to restore proper man-page generation rather than
   documenting a hack with a perl script.  Someday.

I have one real complaint, though: with these patches applied, a "make
htmldocs" generates about 5500 (!) more warnings than it did before.  Over
the last couple of months, I put a bit of focused time into reducing
warnings, and managed to get rid of 20-30 of them.  Now I feel despondent.

I really don't want to add that much noise to the docs build; I think it
will defeat any hope of cleaning up the warnings we already have.  I
wonder if we could suppress warnings about nested structs by default, and
add a flag or envar to turn them back on for those who want them?

In truth, now that I look, the real problem is that the warnings are
repeated many times - as in, like 100 times:

> ./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
> ./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
<107 instances deleted...>
> ./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'

That's not something that used to happen, and is certainly not helpful.
Figuring that out would help a lot.  Can I get you to take a look at
what's going on here?

Thanks,

jon