[PATCH 0/7] The eternal battle against docs-build warnings

[PATCH 0/7] The eternal battle against docs-build warnings

[Jonathan Corbet]

Here's a collection of trivial changes meant to eliminate a number of
"no structured comments found" warnings - plus a kernel-doc tweak to
make those problems easier to track down.

Jonathan Corbet (7):
  docs: Do not seek comments in kernel/rcu/tree_plugin.h
  docs: Fix a misdirected kerneldoc directive
  docs: Do not seek kerneldoc comments in hw-consumer.h
  docs: No structured comments in target_core_device.c
  docs: no structured comments in fs/file_table.c
  docs: No structured comments in include/linux/interconnect.h
  kernel-doc: always name missing kerneldoc sections

 Documentation/core-api/kernel-api.rst            |  2 --
 Documentation/driver-api/basics.rst              |  3 ---
 .../driver-api/firmware/other_interfaces.rst     |  2 +-
 Documentation/driver-api/iio/hw-consumer.rst     |  1 -
 Documentation/driver-api/target.rst              |  4 ++--
 Documentation/filesystems/api-summary.rst        |  3 ---
 Documentation/interconnect/interconnect.rst      |  5 ++---
 scripts/kernel-doc                               | 16 +++++++++-------
 8 files changed, 14 insertions(+), 22 deletions(-)

-- 
2.21.0

[PATCH 1/7] docs: Do not seek comments in kernel/rcu/tree_plugin.h

[Jonathan Corbet]

There are no kerneldoc comments in this file, so do not attempt to
include them in the docs build.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/core-api/kernel-api.rst | 2 --
 Documentation/driver-api/basics.rst   | 3 ---
 2 files changed, 5 deletions(-)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index a29c99d13331..a53ec2eb8176 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -358,8 +358,6 @@ Read-Copy Update (RCU)
 
 .. kernel-doc:: kernel/rcu/tree.c
 
-.. kernel-doc:: kernel/rcu/tree_plugin.h
-
 .. kernel-doc:: kernel/rcu/tree_exp.h
 
 .. kernel-doc:: kernel/rcu/update.c
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index e970fadf4d1a..1ba88c7b3984 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -115,9 +115,6 @@ Kernel utility functions
 .. kernel-doc:: kernel/rcu/tree.c
    :export:
 
-.. kernel-doc:: kernel/rcu/tree_plugin.h
-   :export:
-
 .. kernel-doc:: kernel/rcu/update.c
    :export:
 
-- 
2.21.0

[PATCH 2/7] docs: Fix a misdirected kerneldoc directive

[Jonathan Corbet]

The stratix10 service layer documentation tried to include a kerneldoc
comments for a nonexistent struct; leading to a "no structured comments
found" message.  Switch it to stratix10_svc_command_config_type, which
appears at that spot in the sequence and was not included.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/firmware/other_interfaces.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/firmware/other_interfaces.rst b/Documentation/driver-api/firmware/other_interfaces.rst
index a4ac54b5fd79..b81794e0cfbb 100644
--- a/Documentation/driver-api/firmware/other_interfaces.rst
+++ b/Documentation/driver-api/firmware/other_interfaces.rst
@@ -33,7 +33,7 @@ of the requests on to a secure monitor (EL3).
    :functions: stratix10_svc_client_msg
 
 .. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h
-   :functions: stratix10_svc_command_reconfig_payload
+   :functions: stratix10_svc_command_config_type
 
 .. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h
    :functions: stratix10_svc_cb_data
-- 
2.21.0

[PATCH 3/7] docs: Do not seek kerneldoc comments in hw-consumer.h

[Jonathan Corbet]

There are no kerneldoc comments here, so looking for them just yields a
warning in the docs build.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/iio/hw-consumer.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/driver-api/iio/hw-consumer.rst b/Documentation/driver-api/iio/hw-consumer.rst
index e0fe0b98230e..819fb9edc005 100644
--- a/Documentation/driver-api/iio/hw-consumer.rst
+++ b/Documentation/driver-api/iio/hw-consumer.rst
@@ -45,7 +45,6 @@ A typical IIO HW consumer setup looks like this::
 
 More details
 ============
-.. kernel-doc:: include/linux/iio/hw-consumer.h
 .. kernel-doc:: drivers/iio/buffer/industrialio-hw-consumer.c
    :export:
 
-- 
2.21.0

[PATCH 4/7] docs: No structured comments in target_core_device.c

[Jonathan Corbet]

Documentation/driver-api/target.rst is seeking kerneldoc comments in
drivers/target/target_core_device.c, but no such comments exist.  Take out
the kernel-doc directive and eliminate one warning from the build.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/target.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/target.rst b/Documentation/driver-api/target.rst
index 4363611dd86d..620ec6173a93 100644
--- a/Documentation/driver-api/target.rst
+++ b/Documentation/driver-api/target.rst
@@ -10,8 +10,8 @@ TBD
 Target core device interfaces
 =============================
 
-.. kernel-doc:: drivers/target/target_core_device.c
-    :export:
+This section is blank because no kerneldoc comments have been added to
+drivers/target/target_core_device.c.
 
 Target core transport interfaces
 ================================
-- 
2.21.0

[PATCH 5/7] docs: no structured comments in fs/file_table.c

[Jonathan Corbet]

Remove the kernel-doc directive, since there are only warnings to be found
there.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/filesystems/api-summary.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/filesystems/api-summary.rst b/Documentation/filesystems/api-summary.rst
index aa51ffcfa029..bbb0c1c0e5cf 100644
--- a/Documentation/filesystems/api-summary.rst
+++ b/Documentation/filesystems/api-summary.rst
@@ -89,9 +89,6 @@ Other Functions
 .. kernel-doc:: fs/direct-io.c
    :export:
 
-.. kernel-doc:: fs/file_table.c
-   :export:
-
 .. kernel-doc:: fs/libfs.c
    :export:
 
-- 
2.21.0

[PATCH 6/7] docs: No structured comments in include/linux/interconnect.h

[Jonathan Corbet]

Remove the kernel-doc directive for this file, since there's nothing there
and it generates a warning.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/interconnect/interconnect.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/interconnect/interconnect.rst b/Documentation/interconnect/interconnect.rst
index b8107dcc4cd3..c3e004893796 100644
--- a/Documentation/interconnect/interconnect.rst
+++ b/Documentation/interconnect/interconnect.rst
@@ -89,6 +89,5 @@ Interconnect consumers
 
 Interconnect consumers are the clients which use the interconnect APIs to
 get paths between endpoints and set their bandwidth/latency/QoS requirements
-for these interconnect paths.
-
-.. kernel-doc:: include/linux/interconnect.h
+for these interconnect paths.  These interfaces are not currently
+documented.
-- 
2.21.0

[PATCH 7/7] kernel-doc: always name missing kerneldoc sections

[Jonathan Corbet]

The "no structured comments found" warning is not particularly useful if
there are several invocations, one of which is looking for something
wrong.  So if something specific has been requested, make it clear that
it's the one we weren't able to find.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 scripts/kernel-doc | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3350e498b4ce..c0cb41e65b9b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -285,7 +285,7 @@ use constant {
     OUTPUT_INTERNAL     => 4, # output non-exported symbols
 };
 my $output_selection = OUTPUT_ALL;
-my $show_not_found = 0;
+my $show_not_found = 0;	# No longer used
 
 my @export_file_list;
 
@@ -435,7 +435,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
     } elsif ($cmd eq 'enable-lineno') {
 	    $enable_lineno = 1;
     } elsif ($cmd eq 'show-not-found') {
-	$show_not_found = 1;
+	$show_not_found = 1;  # A no-op but don't fail
     } else {
 	# Unknown argument
         usage();
@@ -2163,12 +2163,14 @@ sub process_file($) {
     }
 
     # Make sure we got something interesting.
-    if ($initial_section_counter == $section_counter) {
-	if ($output_mode ne "none") {
-	    print STDERR "${file}:1: warning: no structured comments found\n";
+    if ($initial_section_counter == $section_counter && $
+	output_mode ne "none") {
+	if ($output_selection == OUTPUT_INCLUDE) {
+	    print STDERR "${file}:1: warning: '$_' not found\n"
+		for keys %function_table;
 	}
-	if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
-	    print STDERR "    Was looking for '$_'.\n" for keys %function_table;
+	else {
+	    print STDERR "${file}:1: warning: no structured comments found\n";
 	}
     }
 }
-- 
2.21.0