linux-kernel - Re: [PATCH 09/16] i2c: busses: i2c-mxs: Demote barely half complete kernel-doc header

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: <YLntC+Sl8MaFFZw4@shikoro>
Date:   Fri, 4 Jun 2021 11:06:19 +0200
From:   Wolfram Sang <wsa@...nel.org>
To:     Lee Jones <lee.jones@...aro.org>
Cc:     linux-kernel@...r.kernel.org, Shawn Guo <shawnguo@...nel.org>,
        Sascha Hauer <s.hauer@...gutronix.de>,
        Pengutronix Kernel Team <kernel@...gutronix.de>,
        Fabio Estevam <festevam@...il.com>,
        NXP Linux Team <linux-imx@....com>,
        Marek Vasut <marex@...x.de>, linux-i2c@...r.kernel.org,
        linux-arm-kernel@...ts.infradead.org
Subject: Re: [PATCH 09/16] i2c: busses: i2c-mxs: Demote barely half complete
 kernel-doc header

> IMHO, we wouldn't want to foster the impression that it's okay to
> provide a non-determined effort, safe in the knowledge that someone
> will come along later and finish the job for them at a later date.

Right.

The first lesson from that is that maintainers should require
documentation of the fields when they get added. This was my oversight
because it was back then not reported by checkers, probably. I am sorry.
It annoys me, too.

If I notice that someone updates a driver which doc-errors, then I ask
if that could be fixed by this person, too. It usually works. Not for
drivers without attention, of course. But this is why I don't mind
doc-errors to stay.

If this is considered problematic, then I'd suggest to remove the kernel
doc headers like you did, but add a comment like:

 * FIXME: add missing fields and reenable kernel-doc

To make sure, it is obvious even by glimpsing through the code that
there is work needed.

Can we agree on that?

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)