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:   Lukas Bulwahn <lukas.bulwahn@gmail.com>
Date:   Mon, 14 Jun 2021 15:49:22 +0200 (CEST)
To:     Dwaipayan Ray <dwaipayanray1@gmail.com>
cc:     corbet@lwn.net, linux-kernel@vger.kernel.org,
        lukas.bulwahn@gmail.com, joe@perches.com, linux-doc@vger.kernel.org
Subject: Re: [PATCH v3] docs: checkpatch: Document and segregate more checkpatch
 message types
In-Reply-To: <20210611060833.1802-1-dwaipayanray1@gmail.com>
Message-ID: <alpine.DEB.2.21.2106141330240.27009@felia>
References: <20210611060833.1802-1-dwaipayanray1@gmail.com>
User-Agent: Alpine 2.21 (DEB 202 2017-01-01)
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Precedence: bulk


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@gmail.com>

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

'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@perches.com/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::
>