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;
From:   "Fabio M. De Francesco" <fmdefrancesco@gmail.com>
To:     Fenghua Yu <fenghua.yu@intel.com>,
        Thomas Gleixner <tglx@linutronix.de>,
        Ingo Molnar <mingo@redhat.com>, Borislav Petkov <bp@alien8.de>,
        "H. Peter Anvin" <hpa@zytor.com>, x86@kernel.org,
        linux-kernel@vger.kernel.org,
        Reinette Chatre <reinette.chatre@intel.com>
Subject: Re: [PATCH v2] x86/resctrl: Fix kernel-doc in pseudo_lock.c
Date:   Mon, 14 Jun 2021 16:52:40 +0200
Message-ID: <2668591.RLH4pUzd2n@linux.local>
In-Reply-To: <4de714ab-47f4-97e3-c35f-184b1218e681@intel.com>
References: <20210608234902.9316-1-fmdefrancesco@gmail.com> <4de714ab-47f4-97e3-c35f-184b1218e681@intel.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 7Bit
Content-Type: text/plain; charset="utf-8"
Precedence: bulk

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