Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Tue, 3 Aug 2021 18:26:19 +0300
From:   Kari Argillander <kari.argillander@gmail.com>
To:     Dan Carpenter <dan.carpenter@oracle.com>
Cc:     Konstantin Komarov <almaz.alexandrovich@paragon-software.com>,
        linux-fsdevel@vger.kernel.org, viro@zeniv.linux.org.uk,
        linux-kernel@vger.kernel.org, pali@kernel.org, dsterba@suse.cz,
        aaptel@suse.com, willy@infradead.org, rdunlap@infradead.org,
        joe@perches.com, mark@harmstone.com, nborisov@suse.com,
        linux-ntfs-dev@lists.sourceforge.net, anton@tuxera.com, hch@lst.de,
        ebiggers@kernel.org, andy.lavr@gmail.com, oleksandr@natalenko.name
Subject: Re: [PATCH] Restyle comments to better align with kernel-doc
Message-ID: <20210803152619.hva737erzqnksfxu@kari-VirtualBox>
References: <20210729134943.778917-1-almaz.alexandrovich@paragon-software.com>
 <20210803115709.zd3gjmxw7oe6b4zk@kari-VirtualBox>
 <20210803133833.GL25548@kadam>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20210803133833.GL25548@kadam>
Precedence: bulk

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!")