linux-kernel - Re: [PATCH v2] x86/resctrl: Fix kernel-doc in pseudo

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: <2668591.RLH4pUzd2n@linux.local>
Date:   Mon, 14 Jun 2021 16:52:40 +0200
From:   "Fabio M. De Francesco" <fmdefrancesco@...il.com>
To:     Fenghua Yu <fenghua.yu@...el.com>,
        Thomas Gleixner <tglx@...utronix.de>,
        Ingo Molnar <mingo@...hat.com>, Borislav Petkov <bp@...en8.de>,
        "H. Peter Anvin" <hpa@...or.com>, x86@...nel.org,
        linux-kernel@...r.kernel.org,
        Reinette Chatre <reinette.chatre@...el.com>
Subject: Re: [PATCH v2] x86/resctrl: Fix kernel-doc in pseudo_lock.c

On Saturday, June 12, 2021 12:09:46 AM CEST Reinette Chatre wrote:
> Hi Fabio,
>
Hi Reinette,
> 
> On 6/8/2021 4:49 PM, Fabio M. De Francesco wrote:
> > Added undocumented parameters, rewrote some phrases, and fixed some
> > formatting issues. Most of the warnings detected by scripts/kernel-doc.
> 
> Please write commit message in imperative tone ... eg, "Add undocumented
> parameters ..."
> 
> Also, please refrain from making changes that are not related to the
> goal. The goal according to the subject of the patch is to fix
> kernel-doc issues - the "rewrote some phrases" is not related to this goal.
> 
> The "rewrote some phrases" really is not clear to me ... you do not
> mention this in your commit message but you seem to also capitalize each
> kernel-doc description? This is not a kernel-doc warning but something
> you chose to do. Please be specific in your commit message about any
> things that are not kernel-doc warnings that you do to warrant it to be
> classified as "Fix kernel-doc". For example, if indeed one of your goals
> are to capitalize all kernel-doc descriptions, add that as a goal to the
> commit log to help reader understand the changes. I think this will also
> help you to consider what is actually an issue and what is your preference.
> 
> When you say "Most of the warnings detected ... " - which warnings did
> it miss? How were other issues detected?
> 
> This patch is unclear regarding its goal - the subject and commit
> message indicate that this is about fixing kernel-doc issue while the
> patch does much more.
> 
I agree with you: I went too far and then I made changes that are not related 
to the goal as stated in the subject: "Fix kernel-doc issues". Obviously the 
same is valid for the patch to internal.h.

I've already removed everything from the pseudo_lock.c patch that should not 
be there and I'm about to send a new version. Soon after this one I'll also 
send a v2 patch to internal.h.

For what is related to style, if you agree with me, I'd like to have it 
consistent: always capitalize the first word which describes a parameter, and 
always use consistent punctuation among different lines and comments, so I'd 
prepare a patch (or a series) to the files in resctrl. I could called them 
"Make consistent use of capitalization and punctuation". What about it? 

I've also noticed some minor grammar issues (e.g., exist -> exits (in 
pseudo_lock.c, line 752 - pseudo-lock -> pseudo-locked in many other lines). 
What do you think if I make a "Fix English grammar" patch? So what about this 
other too?

[cut]

Thanks very much for your review,

Fabio
> 
> Reinette