From 3e893e16af55eeeca8faebabcb36fe78c854ba21 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 8 Dec 2023 16:10:17 -0700 Subject: docs: Raise the minimum Sphinx requirement to 2.4.4 Commit 31abfdda6527 (docs: Deprecate use of Sphinx < 2.4.x) in 6.2 added a warning that support for older versions of Sphinx would be going away. There have been no complaints, so the time has come. Raise the minimum Sphinx version to 2.4.4 and clean out some compatibility code that we no longer need. Reviewed-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/874jgs47fq.fsf@meer.lwn.net Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 1fb88fdceec3..25aefbb35377 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -32,8 +32,7 @@ my $python_cmd = ""; my $activate_cmd; my $min_version; my $cur_version; -my $rec_version = "1.7.9"; # PDF won't build here -my $min_pdf_version = "2.4.4"; # Min version where pdf builds +my $rec_version = "3.4.3"; my $latest_avail_ver; # @@ -791,9 +790,6 @@ sub recommend_sphinx_version($) # Version is OK. Nothing to do. if ($cur_version && ($cur_version ge $rec_version)) { - if ($cur_version lt $min_pdf_version) { - print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n"; - } return; }; @@ -842,10 +838,6 @@ sub recommend_sphinx_version($) printf "\t. $activate_cmd\n"; deactivate_help(); - if ($latest_avail_ver lt $min_pdf_version) { - print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n"; - } - return; } -- cgit From b77fdd6a48e60a0ed1865edbe6d9bf0538551f85 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 13 Dec 2023 23:02:00 -0800 Subject: scripts/kernel-doc: restore warning for Excess struct/union 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 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 08a3e603db19..cb1af401d3ff 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1654,6 +1654,13 @@ sub check_sections($$$$$) { "'$sects[$sx]' " . "description in '$decl_name'\n"); } + elsif (($decl_type eq "struct") or + ($decl_type eq "union")) { + emit_warning("${file}:$.", + "Excess $decl_type member " . + "'$sects[$sx]' " . + "description in '$decl_name'\n"); + } } } } -- cgit From 0c3ebff535956d2718594dc90aa9cc87521ec9fd Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Thu, 14 Dec 2023 16:15:13 -0800 Subject: scripts: kernel-doc: Clarify missing struct member description 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 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cb1af401d3ff..df158c3a9abc 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1601,7 +1601,7 @@ sub push_parameter($$$$$) { $parameterdescs{$param} = $undescribed; if (show_warnings($type, $declaration_name) && $param !~ /\./) { - emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n"); + emit_warning("${file}:$.", "Function parameter or struct member '$param' not described in '$declaration_name'\n"); } } -- cgit From f600c77aeaff6e59806d7eef9ac269a7c1a6d817 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 18 Dec 2023 17:18:08 -0700 Subject: docs: ignore __counted_by attribute in structure definitions 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 | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index df158c3a9abc..6acc39c56ac3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1143,6 +1143,7 @@ sub dump_struct($$) { # strip attributes $members =~ s/\s*$attribute/ /gi; $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos; + $members =~ s/\s*__counted_by\s*\([^;]*\)/ /gos; $members =~ s/\s*__packed\s*/ /gos; $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; -- cgit From dcd39fa2be95efd5cbce74661151f68510cb67fe Mon Sep 17 00:00:00 2001 From: Andy Shevchenko Date: Fri, 15 Dec 2023 17:03:41 +0200 Subject: kernel-doc: Align quick help and the code 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 --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 6acc39c56ac3..3cdc7dba37e3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -23,7 +23,7 @@ kernel-doc - Print formatted kernel documentation to stdout =head1 SYNOPSIS - kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-description] [-Wcontents-before-sections] + kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-desc[ription]] [-Wcontents-before-sections] [ -man | -rst [-sphinx-version VERSION] [-enable-lineno] | -none @@ -328,7 +328,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) { $Werror = 1; } elsif ($cmd eq "Wreturn") { $Wreturn = 1; - } elsif ($cmd eq "Wshort-desc") { + } elsif ($cmd eq "Wshort-desc" or $cmd eq "Wshort-description") { $Wshort_desc = 1; } elsif ($cmd eq "Wcontents-before-sections") { $Wcontents_before_sections = 1; -- cgit From 5889d6ede53bc17252f79c142387e007224aa554 Mon Sep 17 00:00:00 2001 From: Vegard Nossum Date: Mon, 1 Jan 2024 00:59:58 +0100 Subject: scripts/get_abi: fix source path leak The code currently leaks the absolute path of the ABI files into the rendered documentation. There exists code to prevent this, but it is not effective when an absolute path is passed, which it is when $srctree is used. I consider this to be a minimal, stop-gap fix; a better fix would strip off the actual prefix instead of hacking it off with a regex. Link: https://mastodon.social/@vegard/111677490643495163 Cc: Jani Nikula Cc: stable@vger.kernel.org Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231231235959.3342928-1-vegard.nossum@oracle.com --- scripts/get_abi.pl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 0ffd5531242a..408bfd0216da 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -98,7 +98,7 @@ sub parse_abi { $name =~ s,.*/,,; my $fn = $file; - $fn =~ s,Documentation/ABI/,,; + $fn =~ s,.*Documentation/ABI/,,; my $nametag = "File $fn"; $data{$nametag}->{what} = "File $name"; -- cgit From 75ddc07835ab20fcd7b79710ab766bde71873d53 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 28 Dec 2023 15:31:13 -0800 Subject: scripts/get_abi.pl: ignore some temp files When there are filenames of the form ".orig" or ".rej" in the Documenatation/ABI/ subdirectories, there can be confusing or erroneous output generated. Example: the file Documenation/ABI/testing/sysfs-bus-papr-pmem.orig causes this warning message: Documentation/ABI/testing/sysfs-bus-papr-pmem:2: WARNING: unknown document: '/powerpc/papr_hcalls' Prevent this by skipping over filenames that may be created by patch/diff tools etc. Signed-off-by: Randy Dunlap Cc: Greg Kroah-Hartman Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231228233113.5218-1-rdunlap@infradead.org --- scripts/get_abi.pl | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 408bfd0216da..de1c0354b50c 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -93,6 +93,7 @@ sub parse_abi { return if ($mode & S_IFDIR); return if ($file =~ m,/README,); return if ($file =~ m,/\.,); + return if ($file =~ m,\.(rej|org|orig|bak)$,); my $name = $file; $name =~ s,.*/,,; -- cgit From afa751e84c30b517aebd418970d222c39c81acb8 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Mon, 25 Dec 2023 22:52:19 -0800 Subject: kernel-doc: handle a void function without producing a warning 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 --- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3cdc7dba37e3..3ecdab5ca612 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2121,6 +2121,7 @@ sub process_body($$) { } if (/$doc_sect/i) { # case insensitive for supported section names + $in_doc_sect = 1; $newsection = $1; $newcontents = $2; -- cgit