Re: [PATCH v3] docs: checkpatch: Document and segregate more checkpatch message types

[Lukas Bulwahn]

On Fri, 11 Jun 2021, Dwaipayan Ray wrote:

> Add and document more checkpatch message types. About 50% of all
> message types are documented now.
> 
> In addition to this:
> 
> - Create a new subsection 'Indentation and Line Breaks'.
> - Rename subsection 'Comment style' to simply 'Comments'.
> - Refactor some of the existing types to appropriate subsections.
> 
> Signed-off-by: Dwaipayan Ray <dwaipayanray1@xxxxxxxxx>

Reviewed-by: Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx>
Tested-by: Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx>

'make htmldocs' produces no new warnings.

See one further comment on the html presentation below; other than that no 
further comments.

Lukas

> ---
> 
> Changes in v3:
> - Update explanation for CONSTANT_CONVERSION
> - Add more reference links
> - Fix grammatical errors
> 
> Changes in v2:
> - Correct DEVICE_ATTR message types as suggested by Joe Perches.
>   https://lore.kernel.org/lkml/eab0487d7b4e68badbbe0505b2a7903b9d8931c4.camel@xxxxxxxxxxx/T/#t
> - Use passive voice in the documentation
> 
>  Documentation/dev-tools/checkpatch.rst | 397 ++++++++++++++++++++-----
>  1 file changed, 327 insertions(+), 70 deletions(-)
> 
> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
> index 87b859f321de..ad84e709aa25 100644
> --- a/Documentation/dev-tools/checkpatch.rst
> +++ b/Documentation/dev-tools/checkpatch.rst

<snip>
> +
> +  **FUNCTION_ARGUMENTS**
> +    This warning is emitted due to any of the following reasons::

I think here you wnt to have an enumeration, but the "::" makes it
a code block.

> +
> +      1. Arguments for the function declaration do not follow
> +         the identifier name.  Example::
> +
> +           void foo
> +           (int bar, int baz)
> +
> +         This should be corrected to::
> +
> +           void foo(int bar, int baz)
> +
> +      2. Some arguments for the function definition do not
> +         have an identifier name.  Example::
> +
> +           void foo(int)
> +
> +         All arguments should have identifier names.
> +
>    **FUNCTION_WITHOUT_ARGS**
>      Function declarations without arguments like::
>