[Linux-kernel-mentees] [PATCH RFC 0/3] docs: add documentation for checkpatch

[Linux-kernel-mentees] [PATCH RFC 0/3] docs: add documentation for checkpatch

[Dwaipayan Ray]

This patch series serves to introduce a documentation for kernel script
checkpatch.pl (scripts/checkpatch.pl).

A top level tools directory has been created in docs which shall contain
the documentation related to the kernel tools and scripts.

This documentation shall be progressively updated by future patches to
document all the message types in checkpatch. Consecutively this
documentation itself will be parsed by checkpatch to generate verbose
messages.

Dwaipayan Ray (3):
  docs: add documentation for checkpatch
  docs: add documentation for checkpatch
  docs: add documentation for checkpatch

 Documentation/index.rst            |  11 ++
 Documentation/tools/checkpatch.rst | 271 +++++++++++++++++++++++++++++
 Documentation/tools/index.rst      |  10 ++
 3 files changed, 292 insertions(+)
 create mode 100644 Documentation/tools/checkpatch.rst
 create mode 100644 Documentation/tools/index.rst

-- 
2.30.0

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

[Linux-kernel-mentees] [PATCH RFC 1/3] docs: add documentation for checkpatch

[Dwaipayan Ray]

Add documentation for style checker script checkpatch.pl
(scripts/checkpatch.pl).

The documentation performs a dual function. At the surface it
serves as a documentation for checkpatch and describes the options
as well as the messages emitted by checkpatch.

The type description messages will be parsed to enable a verbose
mode in checkpatch.

Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
---
 Documentation/tools/checkpatch.rst | 271 +++++++++++++++++++++++++++++
 1 file changed, 271 insertions(+)
 create mode 100644 Documentation/tools/checkpatch.rst

diff --git a/Documentation/tools/checkpatch.rst b/Documentation/tools/checkpatch.rst
new file mode 100644
index 000000000000..cbf153040de1
--- /dev/null
+++ b/Documentation/tools/checkpatch.rst
@@ -0,0 +1,271 @@
+==========
+Checkpatch
+==========
+
+This document describes the kernel script checkpatch.pl.
+
+.. Table of Contents
+
+	=== 1 Introduction
+	=== 2 Options
+	=== 3 Message Levels
+    === 4 Type Descriptions
+
+1 Introduction
+--------------
+
+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
+judgement should take preference over what checkpatch has to say.  If your code looks
+better with the violations, then its probably best left alone.
+
+
+2 Options
+---------
+
+This section will describe the options checkpatch can be run with.
+
+Usage::
+
+  ./scripts/checkpatch.pl [OPTION]... [FILE]...
+
+Available options:
+
+ - -q,  --quiet
+
+   Enable quiet mode.  All information messages are disabled.  Only the
+   messages and a summary report is output.
+
+ - --no-tree
+
+   Run checkpatch without the kernel tree.
+
+ - --no-signoff
+
+   Disable the 'Signed-off-by' line check.  The sign-off is a simple line at
+   the end of the explanation for the patch, which certifies that you wrote it
+   or otherwise have the right to pass it on as an open-source patch.
+
+   Example::
+
+	 Signed-off-by: Random J Developer <random@developer.example.org>
+
+   Setting this flag effectively stops a message for a missing signed-off-by line
+   in a patch context.
+
+ - --patch
+
+   Treat FILE as a patch.  This is the default option and need not be
+   explicitly specified.
+
+ - --emacs
+
+   Set output to emacs compile window format.  This allows emacs users to jump
+   from the error in the compile window directly to the offending line in the patch.
+
+ - --terse
+
+   Output only one line per report.
+
+ - --showfile
+
+   Show the diffed file position instead of the input file position.
+
+ - -g,  --git
+
+   Treat FILE as a single commit or a git revision range.
+
+   Single commit with:
+
+   - <rev>
+   - <rev>^
+   - <rev>~n
+
+   Multiple commits with:
+
+   - <rev1>..<rev2>
+   - <rev1>...<rev2>
+   - <rev>-<count>
+
+ - -f,  --file
+
+   Treat FILE as a regular source file.  This option must be used when running
+   checkpatch on source files in the kernel.
+
+ - --subjective,  --strict
+
+   Enable stricter tests in checkpatch.  By default the tests emitted as CHECK
+   do not activate by default.  Use this flag to activate the CHECK tests.
+
+ - --list-types
+
+   Every message emitted by checkpatch has an associated TYPE.  Add this flag to
+   display all the types in checkpatch.
+
+   Note that when this flag is active, checkpatch does not read the input FILE, and
+   no message is emitted.  Only a list of types in checkpatch is output.
+
+ - --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.
+
+   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.
+
+   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.
+
+ - --tab-size=n
+
+   Set the number of spaces for tab (default 8).
+
+ - --root=PATH
+
+   PATH to the kernel tree root.
+
+   This option must be specified when invoking checkpatch from outside
+   the kernel root.
+
+ - --no-summary
+
+   Suppress the per file summary.
+
+ - --mailback
+
+   Only produce a report in case of Warnings or Errors.  Milder Checks are
+   excluded from this.
+
+ - --summary-file
+
+   Include the filename in summary.
+
+ - --debug KEY=[0|1]
+
+   Turn on/off debugging of KEY, where KEY is one of 'values', 'possible',
+   'type', and 'attr' (default is all off).
+
+ - --fix
+
+   This is an EXPERIMENTAL feature.  If correctable errors exists, a file
+   <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the
+   automatically fixable errors corrected.
+
+ - --fix-inplace
+
+   EXPERIMENTAL - Similar to --fix but the input file is overwritten with fixes.
+
+   DO NOT USE this flag unless you are absolutely sure and you have a backup in place.
+
+ - --ignore-perl-version
+
+   Override checking of perl version.  Runtime errors maybe encountered after
+   enabling this flag if the perl version does not meet the minimum specified.
+
+ - --codespell
+
+   Use the codespell dictionary for checking spelling errors.
+
+ - --codespellfile
+
+   Use the specified codespell file.  Default is '/usr/share/codespell/dictionary.txt'.
+
+ - --typedefsfile
+
+   Read additional types from this file.
+
+ - --color[=WHEN]
+
+   Use colors 'always', 'never', or only when output is a terminal ('auto').
+   Default is 'auto'.
+
+ - --kconfig-prefix=WORD
+
+   Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`).
+
+ - -h, --help, --version
+
+   Display the help text.
+
+3 Message Levels
+----------------
+
+Messages in checkpatch are divided into three levels. The levels of messages in
+checkpatch denote the severity of the error. They are:
+
+ - ERROR
+
+   This is the most strict level.  Messages of type ERROR must be taken
+   seriously as they denote things that are very likely to be wrong.
+
+ - WARNING
+
+   This is the next stricter level.  Messages of type WARNING requires a
+   more careful review.  But it is milder than an ERROR.
+
+ - CHECK
+
+   This is the mildest level.  These are things which may require some thought.
+
+4 Type Descriptions
+-------------------
+
+This section contains a description of all the message types in checkpatch.
+
+.. Types in this section are also parsed by checkpatch.
+.. Please keep the types sorted alphabetically.
+.. CHECKPATCH_START
+
+MISSING_SIGN_OFF
+
+  The patch is missing a Signed-off-by line.  This error must be taken care of
+  and a Signed-off-by line should be added according to Developer's certificate of
+  Origin.
+
+NO_AUTHOR_SIGN_OFF
+
+  The author of the patch has not signed off the patch.  It is required that
+  a simple sign off line should be present at the end of explanation of the patch
+  to denote that the author has written it or otherwise has the rights to pass it on
+  as an open source patch.
+
+  Sometimes this particular warning can also occur when both email address and name of
+  the author do not match the sign off line because checkpatch has no mechanism to say
+  if it is the same person.
+
+  Consider::
+
+    From: John Doe <john.doe@example.com>
+    ...
+    Signed-off-by: J. Doe <john@example2.com>
+
+  While these may point that both the persons are same, checkpatch cannot
+  understand that and in such cases this warning can be ignored.
+
+.. CHECKPATCH_END
-- 
2.30.0

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 1/3] docs: add documentation for checkpatch

[Lukas Bulwahn]

On Sun, Jan 24, 2021 at 4:19 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
>
> Add documentation for style checker script checkpatch.pl
> (scripts/checkpatch.pl).
>
> The documentation performs a dual function. At the surface it
> serves as a documentation for checkpatch and describes the options
> as well as the messages emitted by checkpatch.
>
> The type description messages will be parsed to enable a verbose
> mode in checkpatch.
>
> Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
> ---
>  Documentation/tools/checkpatch.rst | 271 +++++++++++++++++++++++++++++
>  1 file changed, 271 insertions(+)
>  create mode 100644 Documentation/tools/checkpatch.rst
>
> diff --git a/Documentation/tools/checkpatch.rst b/Documentation/tools/checkpatch.rst
> new file mode 100644
> index 000000000000..cbf153040de1
> --- /dev/null
> +++ b/Documentation/tools/checkpatch.rst
> @@ -0,0 +1,271 @@
> +==========
> +Checkpatch
> +==========
> +
> +This document describes the kernel script checkpatch.pl.
> +
> +.. Table of Contents
> +
> +       === 1 Introduction
> +       === 2 Options
> +       === 3 Message Levels
> +    === 4 Type Descriptions
> +
> +1 Introduction
> +--------------
> +
> +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
> +judgement should take preference over what checkpatch has to say.  If your code looks
> +better with the violations, then its probably best left alone.
> +
> +
> +2 Options
> +---------
> +
> +This section will describe the options checkpatch can be run with.
> +
> +Usage::
> +
> +  ./scripts/checkpatch.pl [OPTION]... [FILE]...
> +
> +Available options:
> +
> + - -q,  --quiet
> +
> +   Enable quiet mode.  All information messages are disabled.  Only the
> +   messages and a summary report is output.
> +
> + - --no-tree
> +
> +   Run checkpatch without the kernel tree.
> +
> + - --no-signoff
> +
> +   Disable the 'Signed-off-by' line check.  The sign-off is a simple line at
> +   the end of the explanation for the patch, which certifies that you wrote it
> +   or otherwise have the right to pass it on as an open-source patch.
> +
> +   Example::
> +
> +        Signed-off-by: Random J Developer <random@developer.example.org>
> +
> +   Setting this flag effectively stops a message for a missing signed-off-by line
> +   in a patch context.
> +
> + - --patch
> +
> +   Treat FILE as a patch.  This is the default option and need not be
> +   explicitly specified.
> +
> + - --emacs
> +
> +   Set output to emacs compile window format.  This allows emacs users to jump
> +   from the error in the compile window directly to the offending line in the patch.
> +
> + - --terse
> +
> +   Output only one line per report.
> +
> + - --showfile
> +
> +   Show the diffed file position instead of the input file position.
> +
> + - -g,  --git
> +
> +   Treat FILE as a single commit or a git revision range.
> +
> +   Single commit with:
> +
> +   - <rev>
> +   - <rev>^
> +   - <rev>~n
> +
> +   Multiple commits with:
> +
> +   - <rev1>..<rev2>
> +   - <rev1>...<rev2>
> +   - <rev>-<count>
> +
> + - -f,  --file
> +
> +   Treat FILE as a regular source file.  This option must be used when running
> +   checkpatch on source files in the kernel.
> +
> + - --subjective,  --strict
> +
> +   Enable stricter tests in checkpatch.  By default the tests emitted as CHECK
> +   do not activate by default.  Use this flag to activate the CHECK tests.
> +
> + - --list-types
> +
> +   Every message emitted by checkpatch has an associated TYPE.  Add this flag to
> +   display all the types in checkpatch.
> +
> +   Note that when this flag is active, checkpatch does not read the input FILE, and
> +   no message is emitted.  Only a list of types in checkpatch is output.
> +
> + - --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.
> +
> +   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.
> +
> +   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.
> +
> + - --tab-size=n
> +
> +   Set the number of spaces for tab (default 8).
> +
> + - --root=PATH
> +
> +   PATH to the kernel tree root.
> +
> +   This option must be specified when invoking checkpatch from outside
> +   the kernel root.
> +
> + - --no-summary
> +
> +   Suppress the per file summary.
> +
> + - --mailback
> +
> +   Only produce a report in case of Warnings or Errors.  Milder Checks are
> +   excluded from this.
> +
> + - --summary-file
> +
> +   Include the filename in summary.
> +
> + - --debug KEY=[0|1]
> +
> +   Turn on/off debugging of KEY, where KEY is one of 'values', 'possible',
> +   'type', and 'attr' (default is all off).
> +
> + - --fix
> +
> +   This is an EXPERIMENTAL feature.  If correctable errors exists, a file
> +   <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the
> +   automatically fixable errors corrected.
> +
> + - --fix-inplace
> +
> +   EXPERIMENTAL - Similar to --fix but the input file is overwritten with fixes.
> +
> +   DO NOT USE this flag unless you are absolutely sure and you have a backup in place.
> +
> + - --ignore-perl-version
> +
> +   Override checking of perl version.  Runtime errors maybe encountered after
> +   enabling this flag if the perl version does not meet the minimum specified.
> +
> + - --codespell
> +
> +   Use the codespell dictionary for checking spelling errors.
> +
> + - --codespellfile
> +
> +   Use the specified codespell file.  Default is '/usr/share/codespell/dictionary.txt'.
> +
> + - --typedefsfile
> +
> +   Read additional types from this file.
> +
> + - --color[=WHEN]
> +
> +   Use colors 'always', 'never', or only when output is a terminal ('auto').
> +   Default is 'auto'.
> +
> + - --kconfig-prefix=WORD
> +
> +   Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`).
> +
> + - -h, --help, --version
> +
> +   Display the help text.
> +

Did you copy this from the current checkpatch.pl --help?

Probably it is best to then refactor checkpatch.pl to just print the
help text by parsing from the Documentation file or have the
Documentation just include the output from checkpatch.pl --help here.

> +3 Message Levels
> +----------------
> +
> +Messages in checkpatch are divided into three levels. The levels of messages in
> +checkpatch denote the severity of the error. They are:
> +
> + - ERROR
> +
> +   This is the most strict level.  Messages of type ERROR must be taken
> +   seriously as they denote things that are very likely to be wrong.
> +
> + - WARNING
> +
> +   This is the next stricter level.  Messages of type WARNING requires a
> +   more careful review.  But it is milder than an ERROR.
> +
> + - CHECK
> +
> +   This is the mildest level.  These are things which may require some thought.
> +
> +4 Type Descriptions
> +-------------------
> +
> +This section contains a description of all the message types in checkpatch.
> +
> +.. Types in this section are also parsed by checkpatch.
> +.. Please keep the types sorted alphabetically.
> +.. CHECKPATCH_START
> +
> +MISSING_SIGN_OFF
> +
> +  The patch is missing a Signed-off-by line.  This error must be taken care of
> +  and a Signed-off-by line should be added according to Developer's certificate of
> +  Origin.
> +
> +NO_AUTHOR_SIGN_OFF
> +
> +  The author of the patch has not signed off the patch.  It is required that
> +  a simple sign off line should be present at the end of explanation of the patch
> +  to denote that the author has written it or otherwise has the rights to pass it on
> +  as an open source patch.
> +
> +  Sometimes this particular warning can also occur when both email address and name of
> +  the author do not match the sign off line because checkpatch has no mechanism to say
> +  if it is the same person.
> +
> +  Consider::
> +
> +    From: John Doe <john.doe@example.com>
> +    ...
> +    Signed-off-by: J. Doe <john@example2.com>
> +
> +  While these may point that both the persons are same, checkpatch cannot
> +  understand that and in such cases this warning can be ignored.
> +
> +.. CHECKPATCH_END
> --
> 2.30.0
>
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 1/3] docs: add documentation for checkpatch

[Dwaipayan Ray]

On Sun, Jan 24, 2021 at 10:11 PM Lukas Bulwahn <lukas.bulwahn@gmail.com> wrote:
>
> On Sun, Jan 24, 2021 at 4:19 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
> >
> > Add documentation for style checker script checkpatch.pl
> > (scripts/checkpatch.pl).
> >
> > The documentation performs a dual function. At the surface it
> > serves as a documentation for checkpatch and describes the options
> > as well as the messages emitted by checkpatch.
> >
> > The type description messages will be parsed to enable a verbose
> > mode in checkpatch.
> >
> > Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
> > ---
> >  Documentation/tools/checkpatch.rst | 271 +++++++++++++++++++++++++++++
> >  1 file changed, 271 insertions(+)
> >  create mode 100644 Documentation/tools/checkpatch.rst
> >
> > diff --git a/Documentation/tools/checkpatch.rst b/Documentation/tools/checkpatch.rst
> > new file mode 100644
> > index 000000000000..cbf153040de1
> > --- /dev/null
> > +++ b/Documentation/tools/checkpatch.rst
> > @@ -0,0 +1,271 @@
> > +==========
> > +Checkpatch
> > +==========
> > +
> > +This document describes the kernel script checkpatch.pl.
> > +
> > +.. Table of Contents
> > +
> > +       === 1 Introduction
> > +       === 2 Options
> > +       === 3 Message Levels
> > +    === 4 Type Descriptions
> > +
> > +1 Introduction
> > +--------------
> > +
> > +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
> > +judgement should take preference over what checkpatch has to say.  If your code looks
> > +better with the violations, then its probably best left alone.
> > +
> > +
> > +2 Options
> > +---------
> > +
> > +This section will describe the options checkpatch can be run with.
> > +
> > +Usage::
> > +
> > +  ./scripts/checkpatch.pl [OPTION]... [FILE]...
> > +
> > +Available options:
> > +
> > + - -q,  --quiet
> > +
> > +   Enable quiet mode.  All information messages are disabled.  Only the
> > +   messages and a summary report is output.
> > +
> > + - --no-tree
> > +
> > +   Run checkpatch without the kernel tree.
> > +
> > + - --no-signoff
> > +
> > +   Disable the 'Signed-off-by' line check.  The sign-off is a simple line at
> > +   the end of the explanation for the patch, which certifies that you wrote it
> > +   or otherwise have the right to pass it on as an open-source patch.
> > +
> > +   Example::
> > +
> > +        Signed-off-by: Random J Developer <random@developer.example.org>
> > +
> > +   Setting this flag effectively stops a message for a missing signed-off-by line
> > +   in a patch context.
> > +
> > + - --patch
> > +
> > +   Treat FILE as a patch.  This is the default option and need not be
> > +   explicitly specified.
> > +
> > + - --emacs
> > +
> > +   Set output to emacs compile window format.  This allows emacs users to jump
> > +   from the error in the compile window directly to the offending line in the patch.
> > +
> > + - --terse
> > +
> > +   Output only one line per report.
> > +
> > + - --showfile
> > +
> > +   Show the diffed file position instead of the input file position.
> > +
> > + - -g,  --git
> > +
> > +   Treat FILE as a single commit or a git revision range.
> > +
> > +   Single commit with:
> > +
> > +   - <rev>
> > +   - <rev>^
> > +   - <rev>~n
> > +
> > +   Multiple commits with:
> > +
> > +   - <rev1>..<rev2>
> > +   - <rev1>...<rev2>
> > +   - <rev>-<count>
> > +
> > + - -f,  --file
> > +
> > +   Treat FILE as a regular source file.  This option must be used when running
> > +   checkpatch on source files in the kernel.
> > +
> > + - --subjective,  --strict
> > +
> > +   Enable stricter tests in checkpatch.  By default the tests emitted as CHECK
> > +   do not activate by default.  Use this flag to activate the CHECK tests.
> > +
> > + - --list-types
> > +
> > +   Every message emitted by checkpatch has an associated TYPE.  Add this flag to
> > +   display all the types in checkpatch.
> > +
> > +   Note that when this flag is active, checkpatch does not read the input FILE, and
> > +   no message is emitted.  Only a list of types in checkpatch is output.
> > +
> > + - --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.
> > +
> > +   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.
> > +
> > +   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.
> > +
> > + - --tab-size=n
> > +
> > +   Set the number of spaces for tab (default 8).
> > +
> > + - --root=PATH
> > +
> > +   PATH to the kernel tree root.
> > +
> > +   This option must be specified when invoking checkpatch from outside
> > +   the kernel root.
> > +
> > + - --no-summary
> > +
> > +   Suppress the per file summary.
> > +
> > + - --mailback
> > +
> > +   Only produce a report in case of Warnings or Errors.  Milder Checks are
> > +   excluded from this.
> > +
> > + - --summary-file
> > +
> > +   Include the filename in summary.
> > +
> > + - --debug KEY=[0|1]
> > +
> > +   Turn on/off debugging of KEY, where KEY is one of 'values', 'possible',
> > +   'type', and 'attr' (default is all off).
> > +
> > + - --fix
> > +
> > +   This is an EXPERIMENTAL feature.  If correctable errors exists, a file
> > +   <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the
> > +   automatically fixable errors corrected.
> > +
> > + - --fix-inplace
> > +
> > +   EXPERIMENTAL - Similar to --fix but the input file is overwritten with fixes.
> > +
> > +   DO NOT USE this flag unless you are absolutely sure and you have a backup in place.
> > +
> > + - --ignore-perl-version
> > +
> > +   Override checking of perl version.  Runtime errors maybe encountered after
> > +   enabling this flag if the perl version does not meet the minimum specified.
> > +
> > + - --codespell
> > +
> > +   Use the codespell dictionary for checking spelling errors.
> > +
> > + - --codespellfile
> > +
> > +   Use the specified codespell file.  Default is '/usr/share/codespell/dictionary.txt'.
> > +
> > + - --typedefsfile
> > +
> > +   Read additional types from this file.
> > +
> > + - --color[=WHEN]
> > +
> > +   Use colors 'always', 'never', or only when output is a terminal ('auto').
> > +   Default is 'auto'.
> > +
> > + - --kconfig-prefix=WORD
> > +
> > +   Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`).
> > +
> > + - -h, --help, --version
> > +
> > +   Display the help text.
> > +
>
> Did you copy this from the current checkpatch.pl --help?
>
> Probably it is best to then refactor checkpatch.pl to just print the
> help text by parsing from the Documentation file or have the
> Documentation just include the output from checkpatch.pl --help here.
>

A part of it is copied actually. And some of the options are more thoroughly
explained with examples like the types and the signoff ones. I think more
examples could be added later on as an entra help.

Maybe it would be better off keeping this separate as checkpatch would take
some time to parse this every time the help message is to be printed?

Apart from that what do you think of it in general?

Thank you,
Dwaipayan.

> > +3 Message Levels
> > +----------------
> > +
> > +Messages in checkpatch are divided into three levels. The levels of messages in
> > +checkpatch denote the severity of the error. They are:
> > +
> > + - ERROR
> > +
> > +   This is the most strict level.  Messages of type ERROR must be taken
> > +   seriously as they denote things that are very likely to be wrong.
> > +
> > + - WARNING
> > +
> > +   This is the next stricter level.  Messages of type WARNING requires a
> > +   more careful review.  But it is milder than an ERROR.
> > +
> > + - CHECK
> > +
> > +   This is the mildest level.  These are things which may require some thought.
> > +
> > +4 Type Descriptions
> > +-------------------
> > +
> > +This section contains a description of all the message types in checkpatch.
> > +
> > +.. Types in this section are also parsed by checkpatch.
> > +.. Please keep the types sorted alphabetically.
> > +.. CHECKPATCH_START
> > +
> > +MISSING_SIGN_OFF
> > +
> > +  The patch is missing a Signed-off-by line.  This error must be taken care of
> > +  and a Signed-off-by line should be added according to Developer's certificate of
> > +  Origin.
> > +
> > +NO_AUTHOR_SIGN_OFF
> > +
> > +  The author of the patch has not signed off the patch.  It is required that
> > +  a simple sign off line should be present at the end of explanation of the patch
> > +  to denote that the author has written it or otherwise has the rights to pass it on
> > +  as an open source patch.
> > +
> > +  Sometimes this particular warning can also occur when both email address and name of
> > +  the author do not match the sign off line because checkpatch has no mechanism to say
> > +  if it is the same person.
> > +
> > +  Consider::
> > +
> > +    From: John Doe <john.doe@example.com>
> > +    ...
> > +    Signed-off-by: J. Doe <john@example2.com>
> > +
> > +  While these may point that both the persons are same, checkpatch cannot
> > +  understand that and in such cases this warning can be ignored.
> > +
> > +.. CHECKPATCH_END
> > --
> > 2.30.0
> >
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 1/3] docs: add documentation for checkpatch

[Lukas Bulwahn]

On Sun, Jan 24, 2021 at 5:53 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
>
> On Sun, Jan 24, 2021 at 10:11 PM Lukas Bulwahn <lukas.bulwahn@gmail.com> wrote:
> >
> > On Sun, Jan 24, 2021 at 4:19 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
> > >
> > > Add documentation for style checker script checkpatch.pl
> > > (scripts/checkpatch.pl).
> > >
> > > The documentation performs a dual function. At the surface it
> > > serves as a documentation for checkpatch and describes the options
> > > as well as the messages emitted by checkpatch.
> > >
> > > The type description messages will be parsed to enable a verbose
> > > mode in checkpatch.
> > >
> > > Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
> > > ---
> > >  Documentation/tools/checkpatch.rst | 271 +++++++++++++++++++++++++++++
> > >  1 file changed, 271 insertions(+)
> > >  create mode 100644 Documentation/tools/checkpatch.rst
> > >
> > > diff --git a/Documentation/tools/checkpatch.rst b/Documentation/tools/checkpatch.rst
> > > new file mode 100644
> > > index 000000000000..cbf153040de1
> > > --- /dev/null
> > > +++ b/Documentation/tools/checkpatch.rst
> > > @@ -0,0 +1,271 @@
> > > +==========
> > > +Checkpatch
> > > +==========
> > > +
> > > +This document describes the kernel script checkpatch.pl.
> > > +
> > > +.. Table of Contents
> > > +
> > > +       === 1 Introduction
> > > +       === 2 Options
> > > +       === 3 Message Levels
> > > +    === 4 Type Descriptions
> > > +
> > > +1 Introduction
> > > +--------------
> > > +
> > > +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
> > > +judgement should take preference over what checkpatch has to say.  If your code looks
> > > +better with the violations, then its probably best left alone.
> > > +
> > > +
> > > +2 Options
> > > +---------
> > > +
> > > +This section will describe the options checkpatch can be run with.
> > > +
> > > +Usage::
> > > +
> > > +  ./scripts/checkpatch.pl [OPTION]... [FILE]...
> > > +
> > > +Available options:
> > > +
> > > + - -q,  --quiet
> > > +
> > > +   Enable quiet mode.  All information messages are disabled.  Only the
> > > +   messages and a summary report is output.
> > > +
> > > + - --no-tree
> > > +
> > > +   Run checkpatch without the kernel tree.
> > > +
> > > + - --no-signoff
> > > +
> > > +   Disable the 'Signed-off-by' line check.  The sign-off is a simple line at
> > > +   the end of the explanation for the patch, which certifies that you wrote it
> > > +   or otherwise have the right to pass it on as an open-source patch.
> > > +
> > > +   Example::
> > > +
> > > +        Signed-off-by: Random J Developer <random@developer.example.org>
> > > +
> > > +   Setting this flag effectively stops a message for a missing signed-off-by line
> > > +   in a patch context.
> > > +
> > > + - --patch
> > > +
> > > +   Treat FILE as a patch.  This is the default option and need not be
> > > +   explicitly specified.
> > > +
> > > + - --emacs
> > > +
> > > +   Set output to emacs compile window format.  This allows emacs users to jump
> > > +   from the error in the compile window directly to the offending line in the patch.
> > > +
> > > + - --terse
> > > +
> > > +   Output only one line per report.
> > > +
> > > + - --showfile
> > > +
> > > +   Show the diffed file position instead of the input file position.
> > > +
> > > + - -g,  --git
> > > +
> > > +   Treat FILE as a single commit or a git revision range.
> > > +
> > > +   Single commit with:
> > > +
> > > +   - <rev>
> > > +   - <rev>^
> > > +   - <rev>~n
> > > +
> > > +   Multiple commits with:
> > > +
> > > +   - <rev1>..<rev2>
> > > +   - <rev1>...<rev2>
> > > +   - <rev>-<count>
> > > +
> > > + - -f,  --file
> > > +
> > > +   Treat FILE as a regular source file.  This option must be used when running
> > > +   checkpatch on source files in the kernel.
> > > +
> > > + - --subjective,  --strict
> > > +
> > > +   Enable stricter tests in checkpatch.  By default the tests emitted as CHECK
> > > +   do not activate by default.  Use this flag to activate the CHECK tests.
> > > +
> > > + - --list-types
> > > +
> > > +   Every message emitted by checkpatch has an associated TYPE.  Add this flag to
> > > +   display all the types in checkpatch.
> > > +
> > > +   Note that when this flag is active, checkpatch does not read the input FILE, and
> > > +   no message is emitted.  Only a list of types in checkpatch is output.
> > > +
> > > + - --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.
> > > +
> > > +   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.
> > > +
> > > +   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.
> > > +
> > > + - --tab-size=n
> > > +
> > > +   Set the number of spaces for tab (default 8).
> > > +
> > > + - --root=PATH
> > > +
> > > +   PATH to the kernel tree root.
> > > +
> > > +   This option must be specified when invoking checkpatch from outside
> > > +   the kernel root.
> > > +
> > > + - --no-summary
> > > +
> > > +   Suppress the per file summary.
> > > +
> > > + - --mailback
> > > +
> > > +   Only produce a report in case of Warnings or Errors.  Milder Checks are
> > > +   excluded from this.
> > > +
> > > + - --summary-file
> > > +
> > > +   Include the filename in summary.
> > > +
> > > + - --debug KEY=[0|1]
> > > +
> > > +   Turn on/off debugging of KEY, where KEY is one of 'values', 'possible',
> > > +   'type', and 'attr' (default is all off).
> > > +
> > > + - --fix
> > > +
> > > +   This is an EXPERIMENTAL feature.  If correctable errors exists, a file
> > > +   <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the
> > > +   automatically fixable errors corrected.
> > > +
> > > + - --fix-inplace
> > > +
> > > +   EXPERIMENTAL - Similar to --fix but the input file is overwritten with fixes.
> > > +
> > > +   DO NOT USE this flag unless you are absolutely sure and you have a backup in place.
> > > +
> > > + - --ignore-perl-version
> > > +
> > > +   Override checking of perl version.  Runtime errors maybe encountered after
> > > +   enabling this flag if the perl version does not meet the minimum specified.
> > > +
> > > + - --codespell
> > > +
> > > +   Use the codespell dictionary for checking spelling errors.
> > > +
> > > + - --codespellfile
> > > +
> > > +   Use the specified codespell file.  Default is '/usr/share/codespell/dictionary.txt'.
> > > +
> > > + - --typedefsfile
> > > +
> > > +   Read additional types from this file.
> > > +
> > > + - --color[=WHEN]
> > > +
> > > +   Use colors 'always', 'never', or only when output is a terminal ('auto').
> > > +   Default is 'auto'.
> > > +
> > > + - --kconfig-prefix=WORD
> > > +
> > > +   Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`).
> > > +
> > > + - -h, --help, --version
> > > +
> > > +   Display the help text.
> > > +
> >
> > Did you copy this from the current checkpatch.pl --help?
> >
> > Probably it is best to then refactor checkpatch.pl to just print the
> > help text by parsing from the Documentation file or have the
> > Documentation just include the output from checkpatch.pl --help here.
> >
>
> A part of it is copied actually. And some of the options are more thoroughly
> explained with examples like the types and the signoff ones. I think more
> examples could be added later on as an entra help.
>
> Maybe it would be better off keeping this separate as checkpatch would take
> some time to parse this every time the help message is to be printed?
>

Well, it is going to be difficult to keep it in sync if it is in two places.
Parsing a file should not take that long... and speed for printing
help is not crucial, nobody is going to call --help hundred or
thousand of times...

> Apart from that what do you think of it in general?
>

I think the whole help text deserves to be restructured, some options
are more standard, others very very special...

Maybe you can think about a good new structure here?

Lukas

> Thank you,
> Dwaipayan.
>
> > > +3 Message Levels
> > > +----------------
> > > +
> > > +Messages in checkpatch are divided into three levels. The levels of messages in
> > > +checkpatch denote the severity of the error. They are:
> > > +
> > > + - ERROR
> > > +
> > > +   This is the most strict level.  Messages of type ERROR must be taken
> > > +   seriously as they denote things that are very likely to be wrong.
> > > +
> > > + - WARNING
> > > +
> > > +   This is the next stricter level.  Messages of type WARNING requires a
> > > +   more careful review.  But it is milder than an ERROR.
> > > +
> > > + - CHECK
> > > +
> > > +   This is the mildest level.  These are things which may require some thought.
> > > +
> > > +4 Type Descriptions
> > > +-------------------
> > > +
> > > +This section contains a description of all the message types in checkpatch.
> > > +
> > > +.. Types in this section are also parsed by checkpatch.
> > > +.. Please keep the types sorted alphabetically.
> > > +.. CHECKPATCH_START
> > > +
> > > +MISSING_SIGN_OFF
> > > +
> > > +  The patch is missing a Signed-off-by line.  This error must be taken care of
> > > +  and a Signed-off-by line should be added according to Developer's certificate of
> > > +  Origin.
> > > +
> > > +NO_AUTHOR_SIGN_OFF
> > > +
> > > +  The author of the patch has not signed off the patch.  It is required that
> > > +  a simple sign off line should be present at the end of explanation of the patch
> > > +  to denote that the author has written it or otherwise has the rights to pass it on
> > > +  as an open source patch.
> > > +
> > > +  Sometimes this particular warning can also occur when both email address and name of
> > > +  the author do not match the sign off line because checkpatch has no mechanism to say
> > > +  if it is the same person.
> > > +
> > > +  Consider::
> > > +
> > > +    From: John Doe <john.doe@example.com>
> > > +    ...
> > > +    Signed-off-by: J. Doe <john@example2.com>
> > > +
> > > +  While these may point that both the persons are same, checkpatch cannot
> > > +  understand that and in such cases this warning can be ignored.
> > > +
> > > +.. CHECKPATCH_END
> > > --
> > > 2.30.0
> > >
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

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

[Dwaipayan Ray]

The tools directory will serve as a documentation for any kernel
tools or scripts.

This links the checkpatch documentation to Sphinx.

Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
---
 Documentation/tools/index.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100644 Documentation/tools/index.rst

diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst
new file mode 100644
index 000000000000..59c9904ef89c
--- /dev/null
+++ b/Documentation/tools/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====
+Tools
+=====
+
+.. toctree::
+   :maxdepth: 2
+
+   checkpatch
\ No newline at end of file
-- 
2.30.0

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

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

[Dwaipayan Ray]

Link the tools directory to the document root for Sphinx.

Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
---
 Documentation/index.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 5888e8a7272f..ddd30e08a440 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -182,6 +182,17 @@ subprojects.
 
    filesystems/ext4/index
 
+Tools Documentation
+-------------------
+
+The documentation in this section provides details about the kernel tools
+and scripts.
+
+.. toctree::
+   :maxdepth: 2
+
+   tools/index
+
 Other documentation
 -------------------
 
-- 
2.30.0

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 3/3] docs: add documentation for checkpatch

[Lukas Bulwahn]

On Sun, Jan 24, 2021 at 4:19 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
>
> Link the tools directory to the document root for Sphinx.
>

Sorry, I did not mean "Documentation/tools/checkpatch.rst"
_literally_; I only remembered that there is a subdirectory for
"tools" in Documentation; and quickly wrote the mail without checking
the actual name of the directory... assuming you would find the
directory I meant.

The directory is called "Documentation/dev-tools", it already has an
index file and the checkpatch.pl documentation fits nicely there.

Luksa

> Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
> ---
>  Documentation/index.rst | 11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 5888e8a7272f..ddd30e08a440 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -182,6 +182,17 @@ subprojects.
>
>     filesystems/ext4/index
>
> +Tools Documentation
> +-------------------
> +
> +The documentation in this section provides details about the kernel tools
> +and scripts.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   tools/index
> +
>  Other documentation
>  -------------------
>
> --
> 2.30.0
>
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 3/3] docs: add documentation for checkpatch

[Dwaipayan Ray]

On Sun, Jan 24, 2021 at 10:08 PM Lukas Bulwahn <lukas.bulwahn@gmail.com> wrote:
>
> On Sun, Jan 24, 2021 at 4:19 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
> >
> > Link the tools directory to the document root for Sphinx.
> >
>
> Sorry, I did not mean "Documentation/tools/checkpatch.rst"
> _literally_; I only remembered that there is a subdirectory for
> "tools" in Documentation; and quickly wrote the mail without checking
> the actual name of the directory... assuming you would find the
> directory I meant.
>

Oh my bad! I actually searched for a while for a directory which contained
the scripts documentations actually and this totally slipped through my eyes.

I will correct the linkage.

> The directory is called "Documentation/dev-tools", it already has an
> index file and the checkpatch.pl documentation fits nicely there.
>
> Luksa
>
> > Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
> > ---
> >  Documentation/index.rst | 11 +++++++++++
> >  1 file changed, 11 insertions(+)
> >
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index 5888e8a7272f..ddd30e08a440 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -182,6 +182,17 @@ subprojects.
> >
> >     filesystems/ext4/index
> >
> > +Tools Documentation
> > +-------------------
> > +
> > +The documentation in this section provides details about the kernel tools
> > +and scripts.
> > +
> > +.. toctree::
> > +   :maxdepth: 2
> > +
> > +   tools/index
> > +
> >  Other documentation
> >  -------------------
> >
> > --
> > 2.30.0
> >
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 3/3] docs: add documentation for checkpatch

[Lukas Bulwahn]

On Sun, Jan 24, 2021 at 5:47 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
>
> On Sun, Jan 24, 2021 at 10:08 PM Lukas Bulwahn <lukas.bulwahn@gmail.com> wrote:
> >
> > On Sun, Jan 24, 2021 at 4:19 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
> > >
> > > Link the tools directory to the document root for Sphinx.
> > >
> >
> > Sorry, I did not mean "Documentation/tools/checkpatch.rst"
> > _literally_; I only remembered that there is a subdirectory for
> > "tools" in Documentation; and quickly wrote the mail without checking
> > the actual name of the directory... assuming you would find the
> > directory I meant.
> >
>
> Oh my bad! I actually searched for a while for a directory which contained
> the scripts documentations actually and this totally slipped through my eyes.
>

Documentation structure is a mess... but it is slowly getting better :)

Lukas

> I will correct the linkage.
>
> > The directory is called "Documentation/dev-tools", it already has an
> > index file and the checkpatch.pl documentation fits nicely there.
> >
> > Luksa
> >
> > > Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
> > > ---
> > >  Documentation/index.rst | 11 +++++++++++
> > >  1 file changed, 11 insertions(+)
> > >
> > > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > > index 5888e8a7272f..ddd30e08a440 100644
> > > --- a/Documentation/index.rst
> > > +++ b/Documentation/index.rst
> > > @@ -182,6 +182,17 @@ subprojects.
> > >
> > >     filesystems/ext4/index
> > >
> > > +Tools Documentation
> > > +-------------------
> > > +
> > > +The documentation in this section provides details about the kernel tools
> > > +and scripts.
> > > +
> > > +.. toctree::
> > > +   :maxdepth: 2
> > > +
> > > +   tools/index
> > > +
> > >  Other documentation
> > >  -------------------
> > >
> > > --
> > > 2.30.0
> > >
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 0/3] docs: add documentation for checkpatch

[Dwaipayan Ray]

On Sun, Jan 24, 2021 at 8:49 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
>
> This patch series serves to introduce a documentation for kernel script
> checkpatch.pl (scripts/checkpatch.pl).
>
> A top level tools directory has been created in docs which shall contain
> the documentation related to the kernel tools and scripts.
>
> This documentation shall be progressively updated by future patches to
> document all the message types in checkpatch. Consecutively this
> documentation itself will be parsed by checkpatch to generate verbose
> messages.
>
> Dwaipayan Ray (3):
>   docs: add documentation for checkpatch
>   docs: add documentation for checkpatch
>   docs: add documentation for checkpatch
>
>  Documentation/index.rst            |  11 ++
>  Documentation/tools/checkpatch.rst | 271 +++++++++++++++++++++++++++++
>  Documentation/tools/index.rst      |  10 ++
>  3 files changed, 292 insertions(+)
>  create mode 100644 Documentation/tools/checkpatch.rst
>  create mode 100644 Documentation/tools/index.rst
>
> --
> 2.30.0
>

Hey Lukas,
This patch series serves to introduce the checkpatch documentation.
A part of this documentation will be used by checkpatch, I am working
on that right now. Subsequently all the message types can be documented
slowly.

The initial plan is to parse the part between
.. CHECKPATCH_START and .. CHECKPATCH_END.

As for the documentation itself, it would be great to have your review on it!
I could send the pdfdocs as well if you need it.

Thank you,
Dwaipayan.
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 0/3] docs: add documentation for checkpatch

[Lukas Bulwahn]

On Sun, Jan 24, 2021 at 4:29 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
>
> On Sun, Jan 24, 2021 at 8:49 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
> >
> > This patch series serves to introduce a documentation for kernel script
> > checkpatch.pl (scripts/checkpatch.pl).
> >
> > A top level tools directory has been created in docs which shall contain
> > the documentation related to the kernel tools and scripts.
> >
> > This documentation shall be progressively updated by future patches to
> > document all the message types in checkpatch. Consecutively this
> > documentation itself will be parsed by checkpatch to generate verbose
> > messages.
> >
> > Dwaipayan Ray (3):
> >   docs: add documentation for checkpatch
> >   docs: add documentation for checkpatch
> >   docs: add documentation for checkpatch
> >
> >  Documentation/index.rst            |  11 ++
> >  Documentation/tools/checkpatch.rst | 271 +++++++++++++++++++++++++++++
> >  Documentation/tools/index.rst      |  10 ++
> >  3 files changed, 292 insertions(+)
> >  create mode 100644 Documentation/tools/checkpatch.rst
> >  create mode 100644 Documentation/tools/index.rst
> >
> > --
> > 2.30.0
> >
>
> Hey Lukas,
> This patch series serves to introduce the checkpatch documentation.
> A part of this documentation will be used by checkpatch, I am working
> on that right now. Subsequently all the message types can be documented
> slowly.
>
> The initial plan is to parse the part between
> .. CHECKPATCH_START and .. CHECKPATCH_END.
>

Plan sounds reasonable, we will refine as we go.

Go ahead and implement the checkpatch.pl feature to parse this file
and output the description, and send it as RFC to Joe as well, but
point out what is important to you for his opinion (I think you care
if the checkpatch.pl implementation can be done that way) and what
will we refine and completely rewrite as we move forward (the
documentation is really much more work in progress).

> As for the documentation itself, it would be great to have your review on it!
> I could send the pdfdocs as well if you need it.
>

All fine, I can pick this patch series and generate the documentation
locally myself.

Lukas
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: [Linux-kernel-mentees] [PATCH RFC 0/3] docs: add documentation for checkpatch

[Lukas Bulwahn]

On Sun, Jan 24, 2021 at 4:19 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
>
> This patch series serves to introduce a documentation for kernel script
> checkpatch.pl (scripts/checkpatch.pl).
>
> A top level tools directory has been created in docs which shall contain
> the documentation related to the kernel tools and scripts.
>
> This documentation shall be progressively updated by future patches to
> document all the message types in checkpatch. Consecutively this
> documentation itself will be parsed by checkpatch to generate verbose
> messages.
>

Just a quick pointer:

I know there was once some documentation at:

https://folk.universitetetioslo.no/knuto/kernel/4.14/dev-tools/run-checkpatch.html

... but now I just checked and it is gone... Knut Omang (the author)
probably left the university.

I could not find it anywhere else;  Maybe you can reach out to him and
ask if he still has those Documentation files around?

It could be useful to reuse his documentation, although it was never merged.

Lukas

> Dwaipayan Ray (3):
>   docs: add documentation for checkpatch
>   docs: add documentation for checkpatch
>   docs: add documentation for checkpatch
>
>  Documentation/index.rst            |  11 ++
>  Documentation/tools/checkpatch.rst | 271 +++++++++++++++++++++++++++++
>  Documentation/tools/index.rst      |  10 ++
>  3 files changed, 292 insertions(+)
>  create mode 100644 Documentation/tools/checkpatch.rst
>  create mode 100644 Documentation/tools/index.rst
>
> --
> 2.30.0
>
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

[PATCH RFC 0/3] checkpatch: add verbose mode

[Dwaipayan Ray]

This patch series adds a verbose mode to checkpatch.
The verbose test descriptions are loaded from the
checkpatch documentation and parsed by checkpatch.

The documentation itself needs more work. More input
on the usage and test descriptions are needed.

Also the visual aspects of the verbose mode needs
some work put into. The usual printing of verbose
descriptions can cause confusion and maybe hard to
distinguish from the actual warnings.

Please note that this is only an initial attempt
and any comments are welcome.

Dwaipayan Ray (3):
  checkpatch: add verbose mode
  docs: add documentation for checkpatch
  docs: add documentation for checkpatch

 Documentation/dev-tools/checkpatch.rst | 283 +++++++++++++++++++++++++
 Documentation/dev-tools/index.rst      |   1 +
 scripts/checkpatch.pl                  |  55 +++++
 3 files changed, 339 insertions(+)
 create mode 100644 Documentation/dev-tools/checkpatch.rst

-- 
2.30.0

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

[Dwaipayan Ray]

Link checkpatch.rst to the dev-tools index for sphinx.

Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
---
 Documentation/dev-tools/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 1b1cf4f5c9d9..43d28998118b 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -14,6 +14,7 @@ whole; patches welcome!
 .. toctree::
    :maxdepth: 2
 
+   checkpatch
    coccinelle
    sparse
    kcov
-- 
2.30.0

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees