user/sven/linux.git/scripts/kernel-doc, branch v6.8.1

Merge tag 'docs-6.8' of git://git.lwn.net/linux

2024-01-12T03:46:52Z

Pull documentation update from Jonathan Corbet: "Another moderately busy cycle for documentation, including: - The minimum Sphinx requirement has been raised to 2.4.4, following a warning that was added in 6.2 - Some reworking of the Documentation/process front page to, hopefully, make it more useful - Various kernel-doc tweaks to, for example, make it deal properly with __counted_by annotations - We have also restored a warning for documentation of nonexistent structure members that disappeared a while back. That had the delightful consequence of adding some 600 warnings to the docs build. A sustained effort by Randy, Vegard, and myself has addressed almost all of those, bringing the documentation back into sync with the code. The fixes are going through the appropriate maintainer trees - Various improvements to the HTML rendered docs, including automatic links to Git revisions and a nice new pulldown to make translations easy to access - Speaking of translations, more of those for Spanish and Chinese ... plus the usual stream of documentation updates and typo fixes" * tag 'docs-6.8' of git://git.lwn.net/linux: (57 commits) MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL A reworked process/index.rst ring-buffer/Documentation: Add documentation on buffer_percent file Translated the RISC-V architecture boot documentation. Docs: remove mentions of fdformat from util-linux Docs/zh_CN: Fix the meaning of DEBUG to pr_debug() Documentation: move driver-api/dcdbas to userspace-api/ Documentation: move driver-api/isapnp to userspace-api/ Documentation/core-api : fix typo in workqueue Documentation/trace: Fixed typos in the ftrace FLAGS section kernel-doc: handle a void function without producing a warning scripts/get_abi.pl: ignore some temp files docs: kernel_abi.py: fix command injection scripts/get_abi: fix source path leak CREDITS, MAINTAINERS, docs/process/howto: Update man-pages' maintainer docs: translations: add translations links when they exist kernel-doc: Align quick help and the code MAINTAINERS: add reviewer for Spanish translations docs: ignore __counted_by attribute in structure definitions scripts: kernel-doc: Clarify missing struct member description ..

kernel-doc: handle a void function without producing a warning

2024-01-03T21:04:31Z

Currently a void function can produce a warning: main.c:469: warning: contents before sections This one is from arch/x86/kernel/cpu/sgx/main.c (which is not included in any produced kernel documentation output). Handle this by setting $in_doc_sect to 1 whenever any recognized document section name is processed. Fixes: f624adef3d0b ("kernel-doc: limit the "section header:" detection to a select few") Signed-off-by: Randy Dunlap Cc: Jani Nikula Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231226065219.319-1-rdunlap@infradead.org

kernel-doc: Align quick help and the code

2023-12-19T21:17:00Z

The update to the quick help mentions -Wshort-description, but code never supported for that. Align that with the code by allowing both: -Wshort-description and -Wshort-desc. Fixes: 56b0f453db74 ("kernel-doc: don't let V=1 change outcome") Signed-off-by: Andy Shevchenko Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231215150341.1996720-1-andriy.shevchenko@linux.intel.com

docs: ignore __counted_by attribute in structure definitions

2023-12-19T00:18:08Z

kernel-doc appeared to ignore __counted_by, but appearances can be deceiving; it caused member names to not be recognized, which manifested as a number of spurious "Excess struct member" warnings. Filter that attribute out and reduce the warning onslaught slightly. Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Clarify missing struct member description

2023-12-15T16:32:27Z

The output "or member" should be more specific, instead saying "struct member". Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231215001513.work.563-kees@kernel.org

scripts/kernel-doc: restore warning for Excess struct/union

2023-12-15T16:17:45Z

The warning for Excess struct or union member description was removed when the $nested parameter of check_sections() was removed. This causes some kernel-doc notation warnings to be missed. Recently the kernel test robot somehow reported an Excess member. The code in kernel-doc has not issued that warning since kernel v4.16, so I don't know how the robot did it. (See the Link for the report.) drivers/net/wireless/intel/iwlwifi/fw/dbg.c:86: warning: Excess struct/union/enum/typedef member 'trans_len' description in 'iwl_fw_dump_ptrs' I patched that warning away even though I could not reproduce the warning from kernel-doc. The warning should be issued for extraneous struct member or union member description, so restore it. Fixes: 1081de2d2f91 ("scripts: kernel-doc: get rid of $nested parameter") Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/all/202312060810.QT9zourt-lkp@intel.com/ Cc: Mauro Carvalho Chehab Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Reviewed-by: Kees Cook Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231214070200.24405-1-rdunlap@infradead.org

cache: enforce cache groups

2023-12-02T22:24:36Z

Set up build time warnings to safeguard against future header changes of organized structs. Warning includes: 1) whether all variables are still in the same cache group 2) whether all the cache groups have the sum of the members size (in the maximum condition, including all members defined in configs) The __cache_group* variables are ignored in kernel-doc check in the various header files they appear in to enforce the cache groups. Suggested-by: Daniel Borkmann Acked-by: Daniel Borkmann Signed-off-by: Coco Li Reviewed-by: Eric Dumazet Reviewed-by: Shakeel Butt Signed-off-by: David S. Miller

scripts/kernel-doc: Fix the regex for matching -Werror flag

2023-10-30T16:52:07Z

Swarup reported a "make htmldocs" warning: Variable length lookbehind is experimental in regex; marked by <-- HERE in m/(?<=^|\s)-Werror(?=$|\s) <-- HERE / at ./scripts/kernel-doc line 188. Akira managed to reproduce it by perl v5.34.0. On second thought, it is not necessary to have the complicated "lookahead and lookbehind" things, and the regex can be simplified. Generally, the kernel-doc warnings should be considered as errors only when "-Werror" flag is set in KCFLAGS, but not when "-Werror=" is set, which means there needs to be a space or start of string before "-Werror", and a space or end of string after "-Werror". The following cases have been tested to work as expected: * kernel-doc warnings are considered as errors: $ KCFLAGS="-Werror" make W=1 $ KCFLAGS="-Wcomment -Werror" make W=1 $ KCFLAGS="-Werror -Wundef" make W=1 $ KCFLAGS="-Wcomment -Werror -Wundef" make W=1 * kernel-doc warnings remain as warnings: $ KCFLAGS="-Werror=return-type" make W=1 $ KCFLAGS="-Wcomment -Werror=return-type" make W=1 $ KCFLAGS="-Werror=return-type -Wundef" make W=1 $ KCFLAGS="-Wcomment -Werror=return-type -Wundef" make W=1 The "Variable length lookbehind is experimental in regex" warning is also resolved by this patch. Fixes: 91f950e8b9d8 ("scripts/kernel-doc: match -Werror flag strictly") Reported-by: Swarup Laxman Kotiaklapudi Signed-off-by: Yujie Liu Closes: https://lore.kernel.org/r/20231028182231.123996-1-swarupkotikalapudi@gmail.com/ Reviewed-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231030085404.3343403-1-yujie.liu@intel.com

scripts/kernel-doc: match -Werror flag strictly

2023-10-23T02:36:49Z

In our CI testing, we use some commands as below to only turn a specific type of warnings into errors, but we notice that kernel-doc warnings are also turned into errors unexpectedly. $ make KCFLAGS="-Werror=return-type" W=1 kernel/fork.o kernel/fork.c:1406: warning: Function parameter or member 'mm' not described in 'set_mm_exe_file' kernel/fork.c:1406: warning: Function parameter or member 'new_exe_file' not described in 'set_mm_exe_file' kernel/fork.c:1441: warning: Function parameter or member 'mm' not described in 'replace_mm_exe_file' kernel/fork.c:1441: warning: Function parameter or member 'new_exe_file' not described in 'replace_mm_exe_file' kernel/fork.c:1491: warning: Function parameter or member 'mm' not described in 'get_mm_exe_file' kernel/fork.c:1510: warning: Function parameter or member 'task' not described in 'get_task_exe_file' kernel/fork.c:1534: warning: Function parameter or member 'task' not described in 'get_task_mm' kernel/fork.c:2109: warning: bad line: kernel/fork.c:2130: warning: Function parameter or member 'ret' not described in '__pidfd_prepare' kernel/fork.c:2130: warning: Excess function parameter 'pidfd' description in '__pidfd_prepare' kernel/fork.c:2179: warning: Function parameter or member 'ret' not described in 'pidfd_prepare' kernel/fork.c:2179: warning: Excess function parameter 'pidfd' description in 'pidfd_prepare' kernel/fork.c:3195: warning: expecting prototype for clone3(). Prototype was for sys_clone3() instead 13 warnings as Errors make[3]: *** [scripts/Makefile.build:243: kernel/fork.o] Error 13 make[3]: *** Deleting file 'kernel/fork.o' make[2]: *** [scripts/Makefile.build:480: kernel] Error 2 make[1]: *** [/root/linux/Makefile:1913: .] Error 2 make: *** [Makefile:234: __sub-make] Error 2 >From the git history, commit 2c12c8103d8f ("scripts/kernel-doc: optionally treat warnings as errors") introduces a new command-line option to make kernel-doc warnings into errors. It can also read the KCFLAGS environment variable to decide whether to turn this option on, but the regex used for matching may not be accurate enough. It can match both "-Werror" and "-Werror=", so the option is turned on by mistake in the latter case. Fix this by strictly matching the flag "-Werror": there must be a space or start of string in the front, and a space or end of string at the end. This can handle all the following cases correctly: KCFLAGS="-Werror" make W=1 [MATCH] KCFLAGS="-Werror=return-type" make W=1 [NO MATCH] KCFLAGS="-Wcomment -Werror -Wundef" make W=1 [MATCH] KCFLAGS="-Wcomment -Werror=return-type -Wundef" make W=1 [NO MATCH] Fixes: 2c12c8103d8f ("scripts/kernel-doc: optionally treat warnings as errors") Signed-off-by: Yujie Liu Signed-off-by: Jonathan Corbet Message-ID: <20231019095637.2471840-1-yujie.liu@intel.com>

scripts: kernel-doc: fix macro handling in enums

2023-08-18T17:14:08Z

drivers/net/ethernet/intel/idpf/idpf.h uses offsetof to initialize the enum enumerators: enum idpf_cap_field { IDPF_BASE_CAPS = -1, IDPF_CSUM_CAPS = offsetof(struct virtchnl2_get_capabilities, csum_caps), IDPF_SEG_CAPS = offsetof(struct virtchnl2_get_capabilities, seg_caps), IDPF_RSS_CAPS = offsetof(struct virtchnl2_get_capabilities, rss_caps), IDPF_HSPLIT_CAPS = offsetof(struct virtchnl2_get_capabilities, hsplit_caps), IDPF_RSC_CAPS = offsetof(struct virtchnl2_get_capabilities, rsc_caps), IDPF_OTHER_CAPS = offsetof(struct virtchnl2_get_capabilities, other_caps), }; kernel-doc parses the above enumerator with a ',' inside the macro and treats 'csum_caps', 'seg_caps' etc. also as enumerators resulting in the warnings: drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'csum_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'seg_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rss_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'hsplit_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rsc_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'other_caps' not described in enum 'idpf_cap_field' Fix it by removing the macro arguments within the parentheses. Cc: Jonathan Corbet Signed-off-by: Pavan Kumar Linga Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20230815210417.98749-3-pavan.kumar.linga@intel.com