Re: [PATCH 2/2] checkpatch: warn on known non-plural rust doc headers

[Benno Lossin]

On 07.09.24 12:53, Joe Perches wrote:
> On Fri, 2024-09-06 at 18:05 +0000, Patrick Miller wrote:
>> Adds a check for documentation in rust file. Warns if certain known
>> documentation headers are not plural. Even though some sections may
>> be singular (i.e. only one example), the header should still be plural
>> so that more examples can be added later without needing to change the
>> header.
>>
>> Fixed the whitespace issue on my previous patch.
> 
> Well, one of them.
> 
>> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> []
>> @@ -3900,6 +3900,13 @@ sub process {
>>  			     "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
>>  		}
>>
>> +# check that document section headers are plural in rust files
>> +		if ($realfile =~ /\.rs$/
>> +			&& $rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Invariant|Guarantee|Panic)\s*$/) {
>> +			WARN( "RUST_DOC_HEADER",
>> +				"Rust doc headers should be plural\n" . $herecurr );
> 
> There is no autoformatter for checkpatch/perl/etc.
> 
> Continuation && on previous line
> No space after open paren
> Align to open paren
> No space before close paren
> 
> I think this is an overly trivial addition.

We want this so we don't have to manually remind people to fix their
documentation sections. Quoting Miguel from the issue [1]:

> We prefer plurals when writing code documentation sections:
> `# Examples`, `# Invariants`, `# Guarantees` and `# Panics`, so that
> it is consistent and so that one can add more examples without having
> to change the section name.

[1]: https://github.com/Rust-for-Linux/linux/issues/1110

---
Cheers,
Benno