The kbuild bot recently added the W=1 option, which triggered
documentation cleanups to squelch hundreds of kernel-doc warnings.
To make sure new kernel contributions don't add regressions to
kernel-doc descriptors, this patch suggests an option to treat
warnings as errors in CI/automated tests.
A -Werror command-line option is added to the kernel-doc script. When
this option is set, the script will return the number of warnings
found. The caller can then treat this positive return value as an
error and stop the build.
Using this command line option is however not straightforward when the
kernel-doc script is called from other scripts. To align with typical
kernel compilation or documentation generation, the Werror option is
also set by checking the KCFLAGS environment variable, or if
KDOC_WERROR is defined, as in the following examples:
KCFLAGS="-Wall -Werror" make W=1 sound/
KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/
KDOC_WERROR=1 make htmldocs
Note that in the last example the documentation build does not stop,
only an additional log is provided.
Credits to Randy Dunlap for suggesting the use of environment variables.
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Link: https://lore.kernel.org/r/20200728162040.92467-1-pierre-louis.bossart@linux.intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit 2165b82fde ("docs: Move kprobes.rst from staging/ to trace/")
moved kprobes.rst, but missed to adjust the MAINTAINERS entry.
Hence, ./scripts/get_maintainer.pl --self-test=patterns complains:
warning: no file matches F: Documentation/staging/kprobes.rst
Adjust the entry to the new file location.
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Acked-by: Naveen N. Rao <naveen.n.rao@linux.vnet.ibm.com>
Link: https://lore.kernel.org/r/20200726055843.10783-1-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There is no flag REMAP_CAN_SHORTEN. Commit eca3654e3c ("vfs: enable
remap callers that can handle short operations") that introduces this
text also introduces the flag REMAP_FILE_CAN_SHORTEN. Change the name
in the documentation accordingly.
Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>
Fixes: eca3654e3c ("vfs: enable remap callers that can handle short operations")
Link: https://lore.kernel.org/r/1595789020-12941-1-git-send-email-Julia.Lawall@inria.fr
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Change the nonexistent flag names WBC_SYNC_ALL and WBC_SYNC_NONE to
WB_SYNC_ALL and WB_SYNC_NONE, respectively, as used in the code with
wbc->sync_mode.
Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>
Link: https://lore.kernel.org/r/1595791341-13209-1-git-send-email-Julia.Lawall@inria.fr
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Underscores were being used for emphasis, but these are rendered verbatim
in HTML output. reStructuredText uses asterisks for emphasis. I *think* I
caught all of them.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Link: https://lore.kernel.org/r/20200727121525.28103-2-vegard.nossum@oracle.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
"xxx``at``" makes the `` appear verbatim in the HTML output. I've opted
for changing this into ``*at()`` to harmonise this with the use of * seen
later in the same document (and add the parentheses to clarify that this
is a system/function call).
``path_``* also makes `` appear in the HTML output, but we can fix it by
moving the * into the ``. Also add the parantheses here.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Link: https://lore.kernel.org/r/20200727121525.28103-1-vegard.nossum@oracle.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200714175528.46712-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
To make it a little clearer how to create a fixes tag,
add an example based on the preceeding gitconfig setup.
Signed-off-by: Tom Rix <trix@redhat.com>
Link: https://lore.kernel.org/r/20200710200115.21176-1-trix@redhat.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit 95ca6d73a8 ("docs: move locking-specific documents to
locking/") accidentally replaced the selftests line for a duplicated
documentation one. Revert this change.
Signed-off-by: André Almeida <andrealmeid@collabora.com>
Fixes: 95ca6d73a8 ("docs: move locking-specific documents to locking/")
Link: https://lore.kernel.org/r/20200715131036.9692-1-andrealmeid@collabora.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The LB_BIAS feature was removed in commit 1c1b8a7b03 ("sched/fair:
Replace source_load() & target_load() with weighted_cpuload()"), so drop
the mention that it is disabled in the no_hz case.
Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>
Link: https://lore.kernel.org/r/1595088518-28116-1-git-send-email-Julia.Lawall@inria.fr
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following warning:
WARNING: Definition list ends without a blank line;
unexpected unindent.
By switching to the literal block syntax.
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-8-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following sphinx warning:
bpf_devel_QA.rst:444: WARNING: Unknown target name:
"documentation/bpf/btf.rst"
No target was defined for 'btf.rst' in the document. Fix it.
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-6-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following warning:
WARNING: toctree contains reference to nonexistent document
'process/unaligned-memory-access'
The path to the document was wrong.
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-5-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following warnings:
tee.rst:65: WARNING: Unexpected indentation.
tee.rst:69: WARNING: Block quote ends without a
blank line; unexpected unindent.
By switching to the 'definition list' syntax.
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-4-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following warning:
WARNING: toctree contains reference to nonexistent document
'admin-guide/mm/nommu-map'
This was due to a typo.
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-1-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following warning:
Documentation/admin-guide/pstore-blk.rst:
WARNING: document isn't included in any toctree
By adding 'pstore-blk.rst' to the index
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-9-dwlsalmeida@gmail.com
Acked-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following warning
Documentation/bpf/ringbuf.rst: WARNING: document isn't
included in any toctree
By adding it to the index.
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-10-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following warning:
Documentation/trace/histogram-design.rst:
WARNING: document isn't included in any toctree
By adding 'histogram-design.rst' to the index.
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-12-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix the following sphinx warning:
Documentation/watch_queue.rst:
WARNING: document isn't included in any toctree
By adding watch_queue.rst to the index.
Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20200718165107.625847-13-dwlsalmeida@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Changelog of commit dcda9b0471 ("mm, tree wide: replace __GFP_REPEAT by
__GFP_RETRY_MAYFAIL with more useful semantic") has very nice description
of GFP flags that affect reclaim behaviour of the page allocator.
It would be pity to keep this description buried in the log so let's expose
it in the Documentation/ as well.
Cc: Michal Hocko <mhocko@suse.com>
Acked-by: Michal Hocko <mhocko@suse.com>
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Link: https://lore.kernel.org/r/20200719153641.231131-1-rppt@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This patch changes:
1) Fix typo in kernel connector documentation.
s/cn_netlink_send_multi/cn_netlink_send_mult/
2) update definition of struct cn_msg
Signed-off-by: Wang Long <w@laoqinren.net>
Link: https://lore.kernel.org/r/1595229852-114071-1-git-send-email-w@laoqinren.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If neither `\bgnu\.org/license`, nor `\bmozilla\.org/MPL\b`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200720211231.63831-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Some of the kprobes references are not valid anymore. Update the URLs to
point to their changed locations, where appropriate. Drop two URLs which
do not exist anymore.
Reported-by: Masami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: Naveen N. Rao <naveen.n.rao@linux.vnet.ibm.com>
Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
Link: https://lore.kernel.org/r/ae96223716e61185870244d8f9dff6678de12fa1.1595331824.git.naveen.n.rao@linux.vnet.ibm.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
modedb.c was moved twice since the modedb documentation was written.
Update the path to the current one.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20200723103454.26167-1-jslaby@suse.cz
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If neither `\bgnu\.org/license`, nor `\bmozilla\.org/MPL\b`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200710062019.28755-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If neither `\bgnu\.org/license`, nor `\bmozilla\.org/MPL\b`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200709182742.24724-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If neither `\bgnu\.org/license`, nor `\bmozilla\.org/MPL\b`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200708202417.22375-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If neither `\bgnu\.org/license`, nor `\bmozilla\.org/MPL\b`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200708161839.15170-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If neither `\bgnu\.org/license`, nor `\bmozilla\.org/MPL\b`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200708145804.14887-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If neither `\bgnu\.org/license`, nor `\bmozilla\.org/MPL\b`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200708123613.14368-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If neither `\bgnu\.org/license`, nor `\bmozilla\.org/MPL\b`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200708081403.13323-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200708062842.12214-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Clean up Documentation/filesystems/proc.rst.
This is basically fixing lots of spelling, grammar, punctuation,
typos, spacing, consistency, section numbering, and headings.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/a5f126e6-d67a-154a-1c87-d8f07542a21c@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Puranjay Mohan