lwn.git/scripts/kernel-doc, branch docs-6.8

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

2024-01-03T21:04:31+00:00

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:00+00:00

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:08+00:00

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:27+00:00

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:45+00:00

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

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

2023-10-30T16:52:07+00:00

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:49+00:00

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:08+00:00

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

scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

2023-08-18T17:14:08+00:00

At present, if the macros DEFINE_DMA_UNMAP_ADDR() and DEFINE_DMA_UNMAP_LEN() are used in the structures as shown below, instead of parsing the parameter in the parentheses, kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and 'DEFINE_DMA_UNMAP_LEN(' which results in the following warnings: drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in 'idpf_tx_buf' drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in 'idpf_tx_buf' struct idpf_tx_buf { DEFINE_DMA_UNMAP_ADDR(dma); DEFINE_DMA_UNMAP_LEN(len); }; Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and DEFINE_DMA_UNMAP_LEN(). Cc: Jonathan Corbet Acked-by: Randy Dunlap Signed-off-by: Pavan Kumar Linga Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20230815210417.98749-2-pavan.kumar.linga@intel.com

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

2023-07-07T05:15:38+00:00

Pull mode documentation updates from Jonathan Corbet: "A half-dozen late arriving docs patches. They are mostly fixes, but we also have a kernel-doc tweak for enums and the long-overdue removal of the outdated and redundant patch-submission comments at the top of the MAINTAINERS file" * tag 'docs-6.5-2' of git://git.lwn.net/linux: scripts: kernel-doc: support private / public marking for enums Documentation: KVM: SEV: add a missing backtick Documentation: ACPI: fix typo in ssdt-overlays.rst Fix documentation of panic_on_warn docs: remove the tips on how to submit patches from MAINTAINERS docs: fix typo in zh_TW and zh_CN translation