linux-kernel - Re: [PATCH] Restyle comments to better align with kernel-doc

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-prev] [thread-next>] [day] [month] [year] [list]

Date:   Tue, 3 Aug 2021 18:26:19 +0300
From:   Kari Argillander <kari.argillander@...il.com>
To:     Dan Carpenter <dan.carpenter@...cle.com>
Cc:     Konstantin Komarov <almaz.alexandrovich@...agon-software.com>,
        linux-fsdevel@...r.kernel.org, viro@...iv.linux.org.uk,
        linux-kernel@...r.kernel.org, pali@...nel.org, dsterba@...e.cz,
        aaptel@...e.com, willy@...radead.org, rdunlap@...radead.org,
        joe@...ches.com, mark@...mstone.com, nborisov@...e.com,
        linux-ntfs-dev@...ts.sourceforge.net, anton@...era.com, hch@....de,
        ebiggers@...nel.org, andy.lavr@...il.com, oleksandr@...alenko.name
Subject: Re: [PATCH] Restyle comments to better align with kernel-doc

On Tue, Aug 03, 2021 at 04:38:33PM +0300, Dan Carpenter wrote:
> Missing subsystem prefix in the subject.

Yeah. I was not sure what to do here because it is patch to patch. I
will do this in the future.

> On Tue, Aug 03, 2021 at 02:57:09PM +0300, Kari Argillander wrote:
> > Capitalize comments and end with period for better reading.
> > 
> > Also function comments are now little more kernel-doc style. This way we
> > can easily convert them to kernel-doc style if we want. Note that these
> > are not yet complete with this style. Example function comments start
> > with /* and in kernel-doc style they start /**.
> > 
> > Use imperative mood in function descriptions.
> > 
> > Change words like ntfs -> NTFS, linux -> Linux.
> > 
> > Use "we" not "I" when commenting code.
> 
> These are all nonsense style guidelines that you invented yourself.  We
> already have too much pointless bureaucracy.  If you can't understand
> the documentation or if there are typos then, sure, fix that.  But let's
> not invent new rules.

You are correct that I "invent" these. My whole point was just make
ntfs3 constant about these rules. I also notice that I didn't make that
clear at patch message and that was huge mistake from my part.

Now in ntfs3 there is mixing commenting styles and I was just trying to make
these nice before merging. I have no preference but it is nice if example one
driver keep things constant.

I would not even try to make these kind of changes if ntfs3 patch series
was already merged to kernel. But probably I will try to bring kernel doc
style funtion comments in future when ntfs3 gets merged.

> (Also it annoys me when people pretend to be stupid "I can't understand
> what a NULL deference is.  Ohhh...  You mean a NULL *pointer*
> dereference!  You left out the word *pointer* so I didn't understand!")