[PATCH] Documentation: checkpatch: Document some more message types

From: Utkarsh Verma
Date: Sat Sep 25 2021 - 12:39:37 EST

Added and documented 3 new message types:

Signed-off-by: Utkarsh Verma <utkarshverma294@xxxxxxxxx>
Documentation/dev-tools/checkpatch.rst | 43 ++++++++++++++++++++++++++
1 file changed, 43 insertions(+)

diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index f0956e9ea2d8..dac5b89a3082 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -710,6 +710,33 @@ Indentation and Line Breaks

See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings

+ A single dereferencing identifier spanned on multiple lines like::
+ struct_identifier->member[index].
+ member = <foo>;
+ is generally hard to follow. It can easily lead to typos and so makes
+ the code vulnerable to bugs.
+ If fixing the multiple line dereferencing leads to an 80 column
+ violation, then either rewrite the code in a more simple way or if the
+ starting part of the dereferencing identifier is the same and used at
+ multiple places then store it in a temporary variable, and use that
+ temporary variable only at all the places. For example, if there are
+ two dereferencing identifiers::
+ member1->member2->member3.foo1;
+ member1->member2->member3.foo2;
+ then store the member1->member2->member3 part in a temporary variable.
+ It not only helps to avoid the 80 column violation but also reduces
+ the program size by removing the unnecessary dereferences.
+ But if none of the above methods work then ignore the 80 column
+ violation because it is much easier to read a dereferencing identifier
+ on a single line.
Trailing statements (for example after any conditional) should be
on the next line.
@@ -845,6 +872,17 @@ Macros, Attributes and Symbols
Use the `fallthrough;` pseudo keyword instead of
`/* fallthrough */` like comments.

+ For the multi-statement macros, it is necessary to use the do-while
+ loop to avoid unpredictable code paths. The do-while loop helps to
+ group the multiple statements into a single one so that a
+ function-like macro can be used as a function only.
+ But for the single statement macros, it is unnecessary to use the
+ do-while loop. Although the code is syntactically correct but using
+ the do-while loop is redundant. So remove the do-while loop for single
+ statement macros.
Using weak declarations like __attribute__((weak)) or __weak
can have unintended link defects. Avoid using them.
@@ -920,6 +958,11 @@ Functions and Variables
Your compiler (or rather your loader) automatically does
it for you.

+ Multiple assignments on a single line makes the code unnecessarily
+ complicated. So on a single line assign value to a single variable
+ only, this makes the code more readable and helps avoid typos.
return is not a function and as such doesn't need parentheses::