scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x

Unfortunately, Sphinx 3.x parser for c functions is too pedantic:

	https://github.com/sphinx-doc/sphinx/issues/8241

While it could be relaxed with some configurations, there are
several corner cases that it would make it hard to maintain,
and will require teaching conf.py about several macros.

So, let's instead use the :c:macro notation. This will
produce an output that it is not as nice as currently, but it
should still be acceptable, and will provide cross-references,
removing thousands of warnings when building with newer
versions of Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 096317ef2e974cdb6846c95dc36f5f37a592fc03..d9783c98f33bfe586302b6936c10d33e24a1a329 100755 (executable)
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -886,19 +886,29 @@ sub output_function_rst(%) {
     my $oldprefix = $lineprefix;
     my $start = "";
 
-    if ($args{'typedef'}) {
-       if ($sphinx_major < 3) {
+    if ($sphinx_major < 3) {
+       if ($args{'typedef'}) {
            print ".. c:type:: ". $args{'function'} . "\n\n";
+           print_lineno($declaration_start_line);
+           print "   **Typedef**: ";
+           $lineprefix = "";
+           output_highlight_rst($args{'purpose'});
+           $start = "\n\n**Syntax**\n\n  ``";
        } else {
-           print ".. c:function:: ". $args{'function'} . "\n\n";
+           print ".. c:function:: ";
        }
-       print_lineno($declaration_start_line);
-       print "   **Typedef**: ";
-       $lineprefix = "";
-       output_highlight_rst($args{'purpose'});
-       $start = "\n\n**Syntax**\n\n  ``";
     } else {
-       print ".. c:function:: ";
+       print ".. c:macro:: ". $args{'function'} . "\n\n";
+
+       if ($args{'typedef'}) {
+           print_lineno($declaration_start_line);
+           print "   **Typedef**: ";
+           $lineprefix = "";
+           output_highlight_rst($args{'purpose'});
+           $start = "\n\n**Syntax**\n\n  ``";
+       } else {
+           print "``";
+       }
     }
     if ($args{'functiontype'} ne "") {
        $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
@@ -925,7 +935,11 @@ sub output_function_rst(%) {
     if ($args{'typedef'}) {
        print ");``\n\n";
     } else {
-       print ")\n\n";
+       if ($sphinx_major < 3) {
+           print ")\n\n";
+       } else {
+           print ")``\n";
+       }
        print_lineno($declaration_start_line);
        $lineprefix = "   ";
        output_highlight_rst($args{'purpose'});