Commit 6e9e4158 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent 5ef09c96

scripts/kernel-doc

+14 −9
Original line number Diff line number Diff line
@@ -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 {

	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";

    }

    if (!$args{'typedef'}) {

	print_lineno($declaration_start_line);

	$lineprefix = "   ";

	output_highlight_rst($args{'purpose'});

CRA Git | Maintained and supported by SUSTech CRA and CCSE