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 for Android: free password hash cracker in your pocket
[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Date:   Tue, 15 Aug 2023 13:15:10 -0500
From:   Carlos Bilbao <carlos.bilbao@....com>
To:     Jonathan Corbet <corbet@....net>,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Cc:     Avadhut Naik <Avadhut.Naik@....com>,
        Miguel Ojeda <ojeda@...nel.org>,
        Akira Yokosawa <akiyks@...il.com>
Subject: [RFC] Proposal to relax warnings of htmldocs

Hello all,

I would like to discuss a recurring issue that we all have encountered
while running `make htmldocs`. The process often generates an overwhelming
amount of warnings that are not relevant to our work, which makes it harder
to identify and address actual warning messages related to our changes.

One of the reasons for this is the variation in warnings raised by
different compilers. For instance, the Linux kernel robot employs Sparse,
which recently raised a warning that we (Avadhut in CC, and then me
reviewing his patch) did not catch during our testing [1,2].

Particularly annoying -to me personally- are warnings of the form:

"warning: Function parameter or member 'field' not described in 'struct'"

that seem to enumerate every single undocumented field within a struct.

I would like to propose something to alleviate this issue before the list
of warnings keeps piling up. 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.

I'm interested in your thoughts and comments. Does anyone have a better
idea regarding this? Maybe someone more experienced in Sphinx can tell us
an alternative way to disable unrelated warnings.

Thanks,
Carlos

Signed-off-by: Carlos Bilbao <carlos.bilbao@....com>

[1] https://lore.kernel.org/all/20230717181602.3468421-1-avadhut.naik@amd.com/
[2] 
https://download.01.org/0day-ci/archive/20230722/202307221642.nEBAfROh-lkp@intel.com/reproduce

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ