[PATCH] scripts: kernel-doc: naming unnamed variadics

[Lothar Rubusch <l.rubusch@xxxxxxxxx>]

Currently the kernel-doc is able to document different types of function
or macro parameters, respectively. Provided an annotation starting with
'@' and the related parameter. Its explanation will appear in the API
docs.

Source        | kernel-doc syntax  | Documentation
--------------+--------------------+--------------------------
func(foo)     | @foo: some desc    | "foo: some desc"
func(foo...)  | @foo...: some desc | "foo: some desc"
func(...)     | @...: some desc    | "...: some desc:
func(...)     | <leave empty>      | "...: variable parameter"

This patch extends the kernel-doc possibilities by:

func(...)     | @...foo: some desc | "foo: some desc"

What is this good for?

Using e.g. a macro with unnamed variadic argument ('...'), in the document
will always show three dots. In practice it is assigned to a specific
variable and represents some entity, not just three dots. In some cases
the name of the entity could make thinks more understandable than using
just the three variadic dots.

Currently this is limited to the only alternative to touch the sources,
and change the unnamed variadic i.e. "..." into a named variadic, e.g.
"foo...".

But shall we rather change the sources to work for the limitations of
our (documentation) scripts, or was it better to improve the scripts
directly to offer that flexibility? Please let the author know if this
feels rather some kind of documentation chindogu, or if it could be
useful?

Signed-off-by: Lothar Rubusch <l.rubusch@xxxxxxxxx>
---
 scripts/kernel-doc | 69 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 49 insertions(+), 20 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f2d73f04e71d..ac5db78d36e9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -469,18 +469,29 @@ sub dump_section {
     my $name = shift;
     my $contents = join "\n", @_;
 
+	my $name_orig = $name;
     if ($name =~ m/$type_param/) {
-	$name = $1;
-	$parameterdescs{$name} = $contents;
-	$sectcheck = $sectcheck . $name . " ";
+		if ($name_orig =~ /^@\.\.\.\w/) {
+			# in case of a '@...name' notation, obtain the variadic argument
+			# from the parsed function/macro, but in the documentation set
+			# the name, cut off the dots
+			$name = $name_orig;
+			$name =~ s/@//;
+		} else {
+			# in in case of named or unnamed variadic arguments
+			$name = $1;
+		}
+		$parameterdescs{$name} = $contents;
+		$sectcheck = $sectcheck . $name . " ";
         $parameterdesc_start_lines{$name} = $new_start_line;
         $new_start_line = 0;
     } elsif ($name eq "@\.\.\.") {
-	$name = "...";
-	$parameterdescs{$name} = $contents;
-	$sectcheck = $sectcheck . $name . " ";
-        $parameterdesc_start_lines{$name} = $new_start_line;
-        $new_start_line = 0;
+		# TODO is this condition actually ever reached?
+		$name = "...";
+		$parameterdescs{$name} = $contents;
+		$sectcheck = $sectcheck . $name . " ";
+		$parameterdesc_start_lines{$name} = $new_start_line;
+		$new_start_line = 0;
     } else {
 	if (defined($sections{$name}) && ($sections{$name} ne "")) {
 	    # Only warn on user specified duplicate section names.
@@ -1442,21 +1453,31 @@ sub push_parameter($$$$) {
 	}
 
 	$anon_struct_union = 0;
-	$param =~ s/[\[\)].*//;
 
+	$param =~ s/[\[\)].*//;
 	if ($type eq "" && $param =~ /\.\.\.$/)
 	{
-	    if (!$param =~ /\w\.\.\.$/) {
-	      # handles unnamed variable parameters
-	      $param = "...";
-	    }
-	    elsif ($param =~ /\w\.\.\.$/) {
-	      # for named variable parameters of the form `x...`, remove the dots
-	      $param =~ s/\.\.\.$//;
-	    }
-	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
-		$parameterdescs{$param} = "variable arguments";
-	    }
+		if ($param =~ /\w\.\.\.$/) {
+			# for named variable parameters of the form `x...`, chop off dots
+			$param =~ s/\.\.\.$//;
+		}
+		else {
+			# has unnamed variadic '...', check with or without description naming
+			my $param_dotprefixed = (grep { $_ =~ /^\.\.\.\w/ } keys %parameterdescs)[0];
+			if (defined $param_dotprefixed) {
+				# handles unnamed variable parameters, but named description
+				$param = $param_dotprefixed;
+				$param =~ s/^\.\.\.//;
+				$parameterdescs{$param} = delete $parameterdescs{$param_dotprefixed};
+			}
+			else {
+				# handles unnamed variable parameters
+				$param = "...";
+			}
+		}
+		if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
+			$parameterdescs{$param} = "variable arguments";
+		}
 	}
 	elsif ($type eq "" && ($param eq "" or $param eq "void"))
 	{
@@ -1527,6 +1548,14 @@ sub check_sections($$$$$) {
 				$err = 0;
 				last;
 			}
+
+			my $sects_nodots = $sects[$sx];
+			$sects_nodots =~ s/^\.\.\.//;
+			if ($prm_clean eq $sects_nodots) {
+				# variadic unnamed parameter, which hase a description name
+				$err = 0;
+				last;
+			}
 		}
 		if ($err) {
 			if ($decl_type eq "function") {
-- 
2.20.1