scripts: kernel-doc: try to use c:function if possible

There are a few namespace clashes by using c:macro everywhere:

basically, when using it, we can't have something like:

	.. c:struct:: pwm_capture

	.. c:macro:: pwm_capture

So, we need to use, instead:

	.. c:function:: int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout)

for the function declaration.

The kernel-doc change was proposed by Jakob Lykke Andersen here:

	https://github.com/jakobandersen/linux_docs/commit/6fd2076ec001cca7466857493cd678df4dfe4a65

Although I did a different implementation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-25-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9875216..2d56c46 100755 (executable)
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -917,6 +917,7 @@ sub output_function_rst(%) {
     my ($parameter, $section);
     my $oldprefix = $lineprefix;
     my $start = "";
+    my $is_macro = 0;
 
     if ($sphinx_major < 3) {
        if ($args{'typedef'}) {
@@ -926,11 +927,17 @@ sub output_function_rst(%) {
            $lineprefix = "";
            output_highlight_rst($args{'purpose'});
            $start = "\n\n**Syntax**\n\n  ``";
+           $is_macro = 1;
        } else {
            print ".. c:function:: ";
        }
     } else {
-       print ".. c:macro:: ". $args{'function'} . "\n\n";
+       if ($args{'typedef'} || $args{'functiontype'} eq "") {
+           $is_macro = 1;
+           print ".. c:macro:: ". $args{'function'} . "\n\n";
+       } else {
+           print ".. c:function:: ";
+       }
 
        if ($args{'typedef'}) {
            print_lineno($declaration_start_line);
@@ -939,7 +946,7 @@ sub output_function_rst(%) {
            output_highlight_rst($args{'purpose'});
            $start = "\n\n**Syntax**\n\n  ``";
        } else {
-           print "``";
+           print "``" if ($is_macro);
        }
     }
     if ($args{'functiontype'} ne "") {
@@ -964,14 +971,12 @@ sub output_function_rst(%) {
            print $type;
        }
     }
-    if ($args{'typedef'}) {
-       print ");``\n\n";
+    if ($is_macro) {
+       print ")``\n\n";
     } else {
-       if ($sphinx_major < 3) {
-           print ")\n\n";
-       } else {
-           print ")``\n";
-       }
+       print ")\n\n";
+    }
+    if (!$args{'typedef'}) {
        print_lineno($declaration_start_line);
        $lineprefix = "   ";
        output_highlight_rst($args{'purpose'});