linux-kernel - Re: [PATCH v4 2/2] docs: add documentation for checkpatch

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Fri, 19 Feb 2021 09:55:40 -0800
From:   Joe Perches <joe@...ches.com>
To:     Dwaipayan Ray <dwaipayanray1@...il.com>
Cc:     lukas.bulwahn@...il.com,
        linux-kernel-mentees@...ts.linuxfoundation.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v4 2/2] docs: add documentation for checkpatch

On Wed, 2021-02-17 at 22:24 +0530, Dwaipayan Ray wrote:
> Add documentation for kernel script checkpatch.pl.
> This documentation is also parsed by checkpatch to
> enable a verbose mode.
> 
> The checkpatch message types are grouped by usage. Under
> each group the types are described briefly. 34 of such
> types are documented.

Of course with more to come as you are work on them... ;)

> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
[]
> +    This applies for all non-functional blocks.
> +    However, there is one special case, namely functions: they have the
> +    opening brace at the beginning of the next line, thus::
> +
> +      int function(int x)
> +      {
> +        body of function
> +      }
> +
> +    Ref: `Documentation/process/coding-style.rst section 3`

Ideally, these Ref: entries should use a form with the specific section
to jump to.  For example:

	Ref: `https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces`

Perhaps "See: " might be better than "Ref: "

	See: `https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces`

> +  **CODE_INDENT**
> +    Code indent should use tabs instead of spaces.
> +    Outside of comments, documentation and Kconfig,
> +    spaces are never used for indentation.
> +    Ref: `Documentation/process/coding-style.rst section 1`

	See: `https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation`

etc...