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

[Joe Perches <joe@perches.com>]

On Sat, 2021-06-05 at 11:29 +0530, Dwaipayan Ray wrote:
> Add and document more checkpatch message types. About 50% of all
> message types are documented now.
[]
> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
[]
> +  **DEVICE_ATTR_FUNCTIONS**
> +    The function names used in DEVICE_ATTR is unusual.
> +    Typically, the store and show functions are named as name_store and
> +    name_show, where name is the device name.

No, it's the variable name of an attribute of a device, not the device name.

    Typically, the store and show functions are used with <attr>_store and
    <attr>_show, where <attr> is a named attribute variable of the device.

> +    Consider the following examples::
> +
> +      static DEVICE_ATTR(type, 0444, type_show, NULL);
> +      static DEVICE_ATTR(power, 0644, power_show, power_store);
> +
> +    The function names should preferably follow the above pattern.
> +
> +    See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
> +
> +  **DEVICE_ATTR_RO**
> +    The DEVICE_ATTR_RO(name) helper macro can be used in place of
> +    DEVICE_ATTR(name, 0444, name_show, NULL);
> +
> +    Note that the macro automatically appends _show to the device name
> +    for the show method.

attribute, etc...

> +  **ENOSYS**
> +    ENOSYS means that a nonexistent system call was called.  We have a
> +    bad habit of using it for things like invalid operations on
> +    otherwise valid syscalls.  This should be avoided in new code.

Please do not use terms like "we".  Just use passive voice and not
any first person/collective words.

> +
> +    See: https://lore.kernel.org/lkml/5eb299021dec23c1a48fa7d9f2c8b794e967766d.1408730669.git.luto@amacapital.net/
> +
> +  **ENOTSUPP**
> +    ENOTSUPP is not a standard error code and should be avoided in new patches.
> +    EOPNOTSUPP should be used instead.

Better word choice is like this section above.