Re: [PATCH v2] x86/resctrl: Fix kernel-doc in pseudo_lock.c

[Fabio M. De Francesco]

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