[Linux-kernel-mentees] [PATCH v2 2/3] docs: add documentation for checkpatch

[Joe Perches]

On Thu, 2021-01-28 at 20:08 +0530, Dwaipayan Ray wrote:
> Add documentation for kernel script checkpatch.pl.
> This documentation is also parsed by checkpatch to
> enable a verbose mode.
> 
> Only a few test descriptions are added and the rest
> will be added later over time to document all the
> message types emitted by checkpatch.

Better to document them all rather than partially.
$ git grep -ohP '(?:\w+|\})\s*\(\s*\"[A-Z_]+"' scripts/checkpatch.pl | \
 cut -f2 -d'"' | sort | uniq
ALLOC_ARRAY_ARGS
ALLOC_SIZEOF_STRUCT
ALLOC_WITH_MULTIPLY
ARCH_DEFINES
ARCH_INCLUDE_LINUX
ARRAY_SIZE
ASSIGN_IN_IF
ASSIGNMENT_CONTINUATIONS
AVOID_BUG
AVOID_EXTERNS
AVOID_L_PREFIX
BAD_SIGN_OFF
BAD_STABLE_ADDRESS_STYLE
BIT_MACRO
BLOCK_COMMENT_STYLE
BOOL_COMPARISON
BRACES
BRACKET_SPACE
CAMELCASE
CHECK
CODE_INDENT
COMMIT_COMMENT_SYMBOL
COMMIT_LOG_LONG_LINE
COMMIT_MESSAGE
COMPARISON_TO_NULL
COMPLEX_MACRO
CONCATENATED_STRING
CONFIG_DESCRIPTION
CONFIG_TYPE_BOOLEAN
CONSIDER_COMPLETION
CONSIDER_KSTRTO
CONSTANT_COMPARISON
CONSTANT_CONVERSION
CONST_CONST
CONST_READ_MOSTLY
CONST_STRUCT
CORRUPTED_PATCH
CVS_KEYWORD
DATA_RACE
DATE_TIME
DEEP_INDENTATION
DEFAULT_NO_BREAK
DEFINE_ARCH_HAS
DEPRECATED_API
DEPRECATED_VARIABLE
DEVICE_ATTR_FUNCTIONS
DEVICE_ATTR_PERMS
DEVICE_ATTR_RO
DEVICE_ATTR_RW
DEVICE_ATTR_WO
DIFF_IN_COMMIT_MSG
DOS_LINE_ENDINGS
DO_WHILE_MACRO_WITH_TRAILING_SEMICOLON
DT_SCHEMA_BINDING_PATCH
DT_SPLIT_BINDING_PATCH
DUPLICATED_SYSCTL_CONST
ELSE_AFTER_BRACE
EMAIL_SUBJECT
EMBEDDED_FILENAME
EMBEDDED_FUNCTION_NAME
ENOSYS
ENOTSUPP
ERROR
EXECUTE_PERMISSIONS
EXPORTED_WORLD_WRITABLE
EXPORT_SYMBOL
FILE_PATH_CHANGES
FROM_SIGN_OFF_MISMATCH
FSF_MAILING_ADDRESS
FUNCTION_ARGUMENTS
FUNCTION_WITHOUT_ARGS
GERRIT_CHANGE_ID
GIT_COMMIT_ID
GLOBAL_INITIALISERS
HEXADECIMAL_BOOLEAN_TEST
HOTPLUG_SECTION
IN_ATOMIC
INCLUDE_LINUX
INDENTED_LABEL
INIT_ATTRIBUTE
INITIALISED_STATIC
INLINE
INLINE_LOCATION
IS_ENABLED_CONFIG
JIFFIES_COMPARISON
KREALLOC_ARG_REUSE
LEADING_SPACE
LIKELY_MISUSE
LINE_CONTINUATIONS
LINE_SPACING
LINUX_VERSION_CODE
LOCKDEP
LOCKING
LOGGING_CONTINUATION
LOGICAL_CONTINUATIONS
LONG_LINE
LONG_UDELAY
MACRO_ARG_PRECEDENCE
MACRO_ARG_REUSE
MACRO_WITH_FLOW_CONTROL
MAINTAINERS_STYLE
MALFORMED_INCLUDE
MASK_THEN_SHIFT
MEMORY_BARRIER
MEMSET
MINMAX
MISORDERED_TYPE
MISPLACED_INIT
MISSING_EOF_NEWLINE
MISSING_SIGN_OFF
MODIFIED_INCLUDE_ASM
MODULE_LICENSE
MSLEEP
MULTILINE_DEREFERENCE
MULTIPLE_ASSIGNMENTS
MULTIPLE_DECLARATION
MULTISTATEMENT_MACRO_USE_DO_WHILE
NAKED_SSCANF
NETWORKING_BLOCK_COMMENT_STYLE
NEW_TYPEDEFS
NO_AUTHOR_SIGN_OFF
NON_OCTAL_PERMISSIONS
NOT_UNIFIED_DIFF
NR_CPUS
OBSOLETE
ONE_SEMICOLON
OOM_MESSAGE
OPEN_BRACE
OPEN_ENDED_LINE
PARENTHESIS_ALIGNMENT
PATCH_PREFIX
POINTER_LOCATION
PREFER_DEFINED_ATTRIBUTE_MACRO
PREFER_DEV_LEVEL
PREFER_ETH_BROADCAST_ADDR
PREFER_ETHER_ADDR_COPY
PREFER_ETHER_ADDR_EQUAL
PREFER_ETH_ZERO_ADDR
PREFER_FALLTHROUGH
PREFER_IS_ENABLED
PREFER_KERNEL_TYPES
PREFER_PR_LEVEL
PREFER_SEQ_PUTS
PRINTF_L
PRINTF_Z
PRINTK_RATELIMITED
PRINTK_WITHOUT_KERN_LEVEL
QUOTED_WHITESPACE_BEFORE_NEWLINE
REPEATED_WORD
RETURN_PARENTHESES
RETURN_VOID
SELF_ASSIGNMENT
SINGLE_STATEMENT_DO_WHILE_MACRO
SIZEOF_ADDRESS
SIZEOF_PARENTHESIS
SPACE_BEFORE_TAB
SPACING
SPDX_LICENSE_TAG
SPLIT_STRING
SSCANF_TO_KSTRTO
STATIC_CONST
STATIC_CONST_CHAR_ARRAY
STORAGE_CLASS
STRING_FRAGMENTS
STRLCPY
SUSPECT_CODE_INDENT
SUSPECT_COMMA_SEMICOLON
SWITCH_CASE_INDENT_LEVEL
SYMBOLIC_PERMS
TABSTOP
TEST_ATTR
TEST_NOT_ATTR
TEST_NOT_TYPE
TEST_TYPE
TRACE_PRINTK
TRACING_LOGGING
TRAILING_SEMICOLON
TRAILING_STATEMENTS
TRAILING_WHITESPACE
TYPECAST_INT_CONSTANT
TYPO_SPELLING
UAPI_INCLUDE
UNCOMMENTED_DEFINITION
UNDOCUMENTED_DT_STRING
UNDOCUMENTED_SETUP
UNKNOWN_COMMIT_ID
UNNECESSARY_BREAK
UNNECESSARY_CASTS
UNNECESSARY_ELSE
UNNECESSARY_INT
UNNECESSARY_KERN_LEVEL
UNNECESSARY_MODIFIER
UNNECESSARY_PARENTHESES
UNSPECIFIED_INT
USE_DEVICE_INITCALL
USE_FUNC
USE_LOCKDEP
USE_NEGATIVE_ERRNO
USE_RELATIVE_PATH
USE_SPINLOCK_T
USLEEP_RANGE
VOLATILE
VSPRINTF_POINTER_EXTENSION
VSPRINTF_SPECIFIER_PX
WAITQUEUE_ACTIVE
WARNING
WEAK_DECLARATION
WHILE_AFTER_BRACE
WHITESPACE_AFTER_LINE_CONTINUATION
YIELD

> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
[]
> +Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial style
> +violations in patches and optionally corrects them.  Checkpatch can also be run on
> +file contexts and without the kernel tree.
> +
> +It should be noted that checkpatch may not be always right.  At times the human

checkpatch is not always right.
Your judgement takes precedence over checkpatch messages.


> +
> + - --types TYPE(,TYPE2...)
> +
> +   Only display messages with the given types.
> +
> +   Example::
> +
> +     ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,NO_AUTHOR_SIGN_OFF
> +
> + - --ignore TYPE(,TYPE2...)
> +
> +   Strip off messages with the given types.

checkpatch will not emit messages for the specified types,

> +
> +   Example::
> +
> +     ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,NO_AUTHOR_SIGN_OFF
> +
> + - --show-types
> +
> +   By default checkpatch doesn't display the type associated with the messages.
> +   Set this flag to show the message type in the output.
> +
> + - --max-line-length=n
> +
> +   Set the max line length (default 100).  On exceeding the given length, a message
> +   is emitted.

If a line exceeds the specified length, a LONG_LINE message is emitted.
> +
> +   The message level is different for patch and file contexts.  For patches, a WARNING is
> +   emitted.  While a milder CHECK is emitted for files.  So for file contexts, the --strict
> +   flag must also be enabled.
> +
> + - --min-conf-desc-length=n
> +
> +   Set the min description length, if shorter, warn.

Kconfig entry minimum description