#!/usr/bin/env perl

# SPDX-License-Identifier: GPL-2.0

use warnings;

use strict;

## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##

## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

## Copyright (C) 2001 Simon Huggins ##

## Copyright (C) 2005-2012 Randy Dunlap ##

## Copyright (C) 2012 Dan Luedtke ##

## ##

## #define enhancements by Armin Kuster <akuster@mvista.com> ##

## Copyright (c) 2000 MontaVista Software, Inc. ##

## ##

## This software falls under the GNU General Public License. ##

## Please read the COPYING file for more information ##

# 18/01/2001 - Cleanups

# Functions prototyped as foo(void) same as foo()

# Stop eval'ing where we don't need to.

# -- huggie@earth.li

# 27/06/2001 - Allowed whitespace after initial "/**" and

# allowed comments before function declarations.

# -- Christian Kreibich <ck@whoop.org>

# Still to do:

# - add perldoc documentation

# - Look more closely at some of the scarier bits :)

# 26/05/2001 - Support for separate source and object trees.

# Return error code.

# Keith Owens <kaos@ocs.com.au>

# 23/09/2001 - Added support for typedefs, structs, enums and unions

# Support for Context section; can be terminated using empty line

# Small fixes (like spaces vs. \s in regex)

# -- Tim Jansen <tim@tjansen.de>

# 25/07/2012 - Added support for HTML5

# -- Dan Luedtke <mail@danrl.de>

sub usage {

my $message = <<"EOF";

Usage: $0 [OPTION ...] FILE ...

Read C language source or header FILEs, extract embedded documentation comments,

and print formatted documentation to standard output.

The documentation comments are identified by "/**" opening comment mark. See

Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.

Output format selection (mutually exclusive):

-man Output troff manual page format. This is the default.

-rst Output reStructuredText format.

-none Do not output documentation, only warnings.

Output selection (mutually exclusive):

-export Only output documentation for symbols that have been

exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()

in any input FILE or -export-file FILE.

-internal Only output documentation for symbols that have NOT been

exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()

in any input FILE or -export-file FILE.

-function NAME Only output documentation for the given function(s)

or DOC: section title(s). All other functions and DOC:

sections are ignored. May be specified multiple times.

-nofunction NAME Do NOT output documentation for the given function(s);

only output documentation for the other functions and

DOC: sections. May be specified multiple times.

Output selection modifiers:

-no-doc-sections Do not output DOC: sections.

-enable-lineno Enable output of #define LINENO lines. Only works with

reStructuredText format.

-export-file FILE Specify an additional FILE in which to look for

EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with

-export or -internal. May be specified multiple times.

Other parameters:

-v Verbose output, more warnings and other information.

-h Print this help.

EOF

print $message;

exit 1;

}

#

# format of comments.

# In the following table, (...)? signifies optional structure.

# (...)* signifies 0 or more structure elements

# /**

# * function_name(:)? (- short description)?

# (* @parameterx: (description of parameter x)?)*

# (* a blank line)?

# * (Description:)? (Description of function)?

# * (section header: (section description)? )*

# (*)?*/

#

# So .. the trivial example would be:

#

# /**

# * my_function

# */

#

# If the Description: header tag is omitted, then there must be a blank line

# after the last parameter specification.

# e.g.

# /**

# * my_function - does my stuff

# * @my_arg: its mine damnit

# *

# * Does my stuff explained.

# */

#

# or, could also use:

# /**

# * my_function - does my stuff

# * @my_arg: its mine damnit

# * Description: Does my stuff explained.

# */

# etc.

#

# Besides functions you can also write documentation for structs, unions,

# enums and typedefs. Instead of the function name you must write the name

# of the declaration; the struct/union/enum/typedef must always precede

# the name. Nesting of declarations is not supported.

# Use the argument mechanism to document members or constants.

# e.g.

# /**

# * struct my_struct - short description

# * @a: first member

# * @b: second member

# *

# * Longer description

# */

# struct my_struct {

# int a;

# int b;

# /* private: */

# int c;

# };

#

# All descriptions can be multiline, except the short function description.

#

# For really longs structs, you can also describe arguments inside the

# body of the struct.

# eg.

# /**

# * struct my_struct - short description

# * @a: first member

# * @b: second member

# *

# * Longer description

# */

# struct my_struct {

# int a;

# int b;

# /**

# * @c: This is longer description of C

# *

# * You can use paragraphs to describe arguments

# * using this method.

# */

# int c;

# };

#

# This should be use only for struct/enum members.

#

# You can also add additional sections. When documenting kernel functions you

# should document the "Context:" of the function, e.g. whether the functions

# can be called form interrupts. Unlike other sections you can end it with an

# empty line.

# A non-void function should have a "Return:" section describing the return

# value(s).

# Example-sections should contain the string EXAMPLE so that they are marked

# appropriately in DocBook.

#

# Example:

# /**

# * user_function - function that can only be called in user context

# * @a: some argument

# * Context: !in_interrupt()

# *

# * Some description

# * Example:

# * user_function(22);

# */

# ...

#

#

# All descriptive text is further processed, scanning for the following special

# patterns, which are highlighted appropriately.

#

# 'funcname()' - function

# '$ENVVAR' - environmental variable

# '&struct_name' - name of a structure (up to two words including 'struct')

# '&struct_name.member' - name of a structure member

# '@parameter' - name of a parameter

# '%CONST' - name of a constant.

# '``LITERAL``' - literal string without any spaces on it.

## init lots of data

my $errors = 0;

my $warnings = 0;

my $anon_struct_union = 0;

# match expressions used to find embedded type information

my $type_constant = '\b``([^\`]+)``\b';

my $type_constant2 = '\%([-_\w]+)';

my $type_func = '(\w+)\(\)';

my $type_param = '\@(\w*(\.\w+)*(\.\.\.)?)';

my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params

my $type_env = '(\$\w+)';

my $type_enum = '\&(enum\s*([_\w]+))';

my $type_struct = '\&(struct\s*([_\w]+))';

my $type_typedef = '\&(typedef\s*([_\w]+))';

my $type_union = '\&(union\s*([_\w]+))';

my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';

my $type_fallback = '\&([_\w]+)';

my $type_member_func = $type_member . '\(\)';

# Output conversion substitutions.

# One for each output format

# these are pretty rough

my @highlights_man = (

[$type_constant, "\$1"],

[$type_constant2, "\$1"],

[$type_func, "\\\\fB\$1\\\\fP"],

[$type_enum, "\\\\fI\$1\\\\fP"],

[$type_struct, "\\\\fI\$1\\\\fP"],

[$type_typedef, "\\\\fI\$1\\\\fP"],

[$type_union, "\\\\fI\$1\\\\fP"],

[$type_param, "\\\\fI\$1\\\\fP"],

[$type_member, "\\\\fI\$1\$2\$3\\\\fP"],

[$type_fallback, "\\\\fI\$1\\\\fP"]

);

my $blankline_man = "";

# rst-mode

my @highlights_rst = (

[$type_constant, "``\$1``"],

[$type_constant2, "``\$1``"],

# Note: need to escape () to avoid func matching later

[$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],

[$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],

[$type_fp_param, "**\$1\\\\(\\\\)**"],

[$type_func, "\\:c\\:func\\:`\$1()`"],

[$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],

[$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],

[$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],

[$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],

# in rst this can refer to any type

[$type_fallback, "\\:c\\:type\\:`\$1`"],

[$type_param, "**\$1**"]

);

my $blankline_rst = "\n";

# read arguments

if ($#ARGV == -1) {

usage();

}

my $kernelversion;

my $dohighlight = "";

my $verbose = 0;

my $output_mode = "rst";

my $output_preformatted = 0;

my $no_doc_sections = 0;

my $enable_lineno = 0;

my @highlights = @highlights_rst;

my $blankline = $blankline_rst;

my $modulename = "Kernel API";

use constant {

OUTPUT_ALL => 0, # output all symbols and doc sections

OUTPUT_INCLUDE => 1, # output only specified symbols

OUTPUT_EXCLUDE => 2, # output everything except specified symbols

OUTPUT_EXPORTED => 3, # output exported symbols

OUTPUT_INTERNAL => 4, # output non-exported symbols

};

my $output_selection = OUTPUT_ALL;

my $show_not_found = 0;

my @export_file_list;

my @build_time;

if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&

(my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {

@build_time = gmtime($seconds);

} else {

@build_time = localtime;

}

my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',

'July', 'August', 'September', 'October',

'November', 'December')[$build_time[4]] .

" " . ($build_time[5]+1900);

# Essentially these are globals.

# They probably want to be tidied up, made more localised or something.

# CAVEAT EMPTOR! Some of the others I localised may not want to be, which

# could cause "use of undefined value" or other bugs.

my ($function, %function_table, %parametertypes, $declaration_purpose);

my $declaration_start_line;

my ($type, $declaration_name, $return_type);

my ($newsection, $newcontents, $prototype, $brcount, %source_map);

if (defined($ENV{'KBUILD_VERBOSE'})) {

$verbose = "$ENV{'KBUILD_VERBOSE'}";

}

# Generated docbook code is inserted in a template at a point where

# docbook v3.1 requires a non-zero sequence of RefEntry's; see:

# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html

# We keep track of number of generated entries and generate a dummy

# if needs be to ensure the expanded template can be postprocessed

# into html.

my $section_counter = 0;

my $lineprefix="";

# Parser states

use constant {

STATE_NORMAL => 0, # normal code

STATE_NAME => 1, # looking for function name

STATE_BODY_MAYBE => 2, # body - or maybe more description

STATE_BODY => 3, # the body of the comment

STATE_PROTO => 4, # scanning prototype

STATE_DOCBLOCK => 5, # documentation block

STATE_INLINE => 6, # gathering documentation outside main block

};

my $state;

my $in_doc_sect;

my $leading_space;

# Inline documentation state

use constant {

STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)

STATE_INLINE_NAME => 1, # looking for member name (@foo:)

STATE_INLINE_TEXT => 2, # looking for member documentation

STATE_INLINE_END => 3, # done

STATE_INLINE_ERROR => 4, # error - Comment without header was found.

# Spit a warning as it's not

# proper kernel-doc and ignore the rest.

};

my $inline_doc_state;

#declaration types: can be

# 'function', 'struct', 'union', 'enum', 'typedef'

my $decl_type;

my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.

my $doc_end = '\*/';

my $doc_com = '\s*\*\s*';

my $doc_com_body = '\s*\* ?';

my $doc_decl = $doc_com . '(\w+)';

# @params and a strictly limited set of supported section names

my $doc_sect = $doc_com .

'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';

my $doc_content = $doc_com_body . '(.*)';

my $doc_block = $doc_com . 'DOC:\s*(.*)?';

my $doc_inline_start = '^\s*/\*\*\s*$';

my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';

my $doc_inline_end = '^\s*\*/\s*$';

my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';

my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';

my %parameterdescs;

my %parameterdesc_start_lines;

my @parameterlist;

my %sections;

my @sectionlist;

my %section_start_lines;

my $sectcheck;

my $struct_actual;

my $contents = "";

my $new_start_line = 0;

# the canonical section names. see also $doc_sect above.

my $section_default = "Description"; # default section

my $section_intro = "Introduction";

my $section = $section_default;

my $section_context = "Context";

my $section_return = "Return";

my $undescribed = "-- undescribed --";

reset_state();

while ($ARGV[0] =~ m/^--?(.*)/) {

my $cmd = $1;

shift @ARGV;

if ($cmd eq "man") {

$output_mode = "man";

@highlights = @highlights_man;

$blankline = $blankline_man;

} elsif ($cmd eq "rst") {

$output_mode = "rst";

@highlights = @highlights_rst;

$blankline = $blankline_rst;

} elsif ($cmd eq "none") {

$output_mode = "none";

} elsif ($cmd eq "module") { # not needed for XML, inherits from calling document

$modulename = shift @ARGV;

} elsif ($cmd eq "function") { # to only output specific functions

$output_selection = OUTPUT_INCLUDE;

$function = shift @ARGV;

$function_table{$function} = 1;

} elsif ($cmd eq "nofunction") { # output all except specific functions

$output_selection = OUTPUT_EXCLUDE;

$function = shift @ARGV;

$function_table{$function} = 1;

} elsif ($cmd eq "export") { # only exported symbols

$output_selection = OUTPUT_EXPORTED;

%function_table = ();

} elsif ($cmd eq "internal") { # only non-exported symbols

$output_selection = OUTPUT_INTERNAL;

%function_table = ();

} elsif ($cmd eq "export-file") {

my $file = shift @ARGV;

push(@export_file_list, $file);

} elsif ($cmd eq "v") {

$verbose = 1;

} elsif (($cmd eq "h") || ($cmd eq "help")) {

usage();

} elsif ($cmd eq 'no-doc-sections') {

$no_doc_sections = 1;

} elsif ($cmd eq 'enable-lineno') {

$enable_lineno = 1;

} elsif ($cmd eq 'show-not-found') {

$show_not_found = 1;

} else {

# Unknown argument

usage();

}

}

# continue execution near EOF;

# get kernel version from env

sub get_kernel_version() {

my $version = 'unknown kernel version';

if (defined($ENV{'KERNELVERSION'})) {

$version = $ENV{'KERNELVERSION'};

}

return $version;

}

#

sub print_lineno {

my $lineno = shift;

if ($enable_lineno && defined($lineno)) {

print "#define LINENO " . $lineno . "\n";

}

}

##

# dumps section contents to arrays/hashes intended for that purpose.

#

sub dump_section {

my $file = shift;

my $name = shift;

my $contents = join "\n", @_;

if ($name =~ m/$type_param/) {

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

} else {

if (defined($sections{$name}) && ($sections{$name} ne "")) {

# Only warn on user specified duplicate section names.

if ($name ne $section_default) {

print STDERR "${file}:$.: warning: duplicate section name '$name'\n";

++$warnings;

}

$sections{$name} .= $contents;

} else {

$sections{$name} = $contents;

push @sectionlist, $name;

$section_start_lines{$name} = $new_start_line;

$new_start_line = 0;

}

}

}

##

# dump DOC: section after checking that it should go out

#

sub dump_doc_section {

my $file = shift;

my $name = shift;

my $contents = join "\n", @_;

if ($no_doc_sections) {

return;

}

if (($output_selection == OUTPUT_ALL) ||

($output_selection == OUTPUT_INCLUDE &&

defined($function_table{$name})) ||

($output_selection == OUTPUT_EXCLUDE &&

!defined($function_table{$name})))

{

dump_section($file, $name, $contents);

output_blockhead({'sectionlist' => \@sectionlist,

'sections' => \%sections,

'module' => $modulename,

'content-only' => ($output_selection != OUTPUT_ALL), });

}

}

##

# output function

#

# parameterdescs, a hash.

# function => "function name"

# parameterlist => @list of parameters

# parameterdescs => %parameter descriptions

# sectionlist => @list of sections

# sections => %section descriptions

#

sub output_highlight {

my $contents = join "\n",@_;

my $line;

# DEBUG

# if (!defined $contents) {

# use Carp;

# confess "output_highlight got called with no args?\n";

# }

# print STDERR "contents b4:$contents\n";

eval $dohighlight;

die $@ if $@;

# print STDERR "contents af:$contents\n";

foreach $line (split "\n", $contents) {

if (! $output_preformatted) {

$line =~ s/^\s*//;

}

if ($line eq ""){

if (! $output_preformatted) {

print $lineprefix, $blankline;

}

} else {

if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {

print "\\&$line";

} else {

print $lineprefix, $line;

}

}

print "\n";

}

}

##

# output function in man

sub output_function_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

my $count;

print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";

print ".SH NAME\n";

print $args{'function'} . " \\- " . $args{'purpose'} . "\n";

print ".SH SYNOPSIS\n";

if ($args{'functiontype'} ne "") {

print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";

} else {

print ".B \"" . $args{'function'} . "\n";

}

$count = 0;

my $parenth = "(";

my $post = ",";

foreach my $parameter (@{$args{'parameterlist'}}) {

if ($count == $#{$args{'parameterlist'}}) {

$post = ");";

}

$type = $args{'parametertypes'}{$parameter};

if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {

# pointer-to-function

print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";

} else {

$type =~ s/([^\*])$/$1 /;

print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";

}

$count++;

$parenth = "";

}

print ".SH ARGUMENTS\n";

foreach $parameter (@{$args{'parameterlist'}}) {

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

print ".IP \"" . $parameter . "\" 12\n";

output_highlight($args{'parameterdescs'}{$parameter_name});

}

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"", uc $section, "\"\n";

output_highlight($args{'sections'}{$section});

}

}

##

# output enum in man

sub output_enum_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

my $count;

print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";

print ".SH NAME\n";

print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";

print ".SH SYNOPSIS\n";

print "enum " . $args{'enum'} . " {\n";

$count = 0;

foreach my $parameter (@{$args{'parameterlist'}}) {

print ".br\n.BI \" $parameter\"\n";

if ($count == $#{$args{'parameterlist'}}) {

print "\n};\n";

last;

}

else {

print ", \n.br\n";

}

$count++;

}

print ".SH Constants\n";

foreach $parameter (@{$args{'parameterlist'}}) {

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

print ".IP \"" . $parameter . "\" 12\n";

output_highlight($args{'parameterdescs'}{$parameter_name});

}

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"$section\"\n";

output_highlight($args{'sections'}{$section});

}

}

##

# output struct in man

sub output_struct_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";

print ".SH NAME\n";

print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";

my $declaration = $args{'definition'};

$declaration =~ s/\t/ /g;

$declaration =~ s/\n/"\n.br\n.BI \"/g;

print ".SH SYNOPSIS\n";

print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";

print ".BI \"$declaration\n};\n.br\n\n";

print ".SH Members\n";

foreach $parameter (@{$args{'parameterlist'}}) {

($parameter =~ /^#/) && next;

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

print ".IP \"" . $parameter . "\" 12\n";

output_highlight($args{'parameterdescs'}{$parameter_name});

}

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"$section\"\n";

output_highlight($args{'sections'}{$section});

}

}

##

# output typedef in man

sub output_typedef_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";

print ".SH NAME\n";

print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"$section\"\n";

output_highlight($args{'sections'}{$section});

}

}

sub output_blockhead_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

my $count;

print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"$section\"\n";

output_highlight($args{'sections'}{$section});

}

}

##

# output in restructured text

#

#

# This could use some work; it's used to output the DOC: sections, and

# starts by putting out the name of the doc section itself, but that tends

# to duplicate a header already in the template file.

#

sub output_blockhead_rst(%) {

my %args = %{$_[0]};

my ($parameter, $section);

foreach $section (@{$args{'sectionlist'}}) {

if ($output_selection != OUTPUT_INCLUDE) {

print "**$section**\n\n";

}

print_lineno($section_start_lines{$section});

output_highlight_rst($args{'sections'}{$section});

print "\n";

}

}

#

# Apply the RST highlights to a sub-block of text.

#

sub highlight_block($) {

# The dohighlight kludge requires the text be called $contents

my $contents = shift;

eval $dohighlight;

die $@ if $@;

return $contents;

}

#

# Regexes used only here.

#

my $sphinx_literal = '^[^.].*::$';

my $sphinx_cblock = '^\.\.\ +code-block::';

sub output_highlight_rst {

my $input = join "\n",@_;

my $output = "";

my $line;

my $in_literal = 0;

my $litprefix;

my $block = "";

foreach $line (split "\n",$input) {

#

# If we're in a literal block, see if we should drop out

# of it. Otherwise pass the line straight through unmunged.

#

if ($in_literal) {

if (! ($line =~ /^\s*$/)) {

#

# If this is the first non-blank line in a literal

# block we need to figure out what the proper indent is.

#

if ($litprefix eq "") {

$line =~ /^(\s*)/;

$litprefix = '^' . $1;

$output .= $line . "\n";

} elsif (! ($line =~ /$litprefix/)) {

$in_literal = 0;

} else {

$output .= $line . "\n";

}

} else {

$output .= $line . "\n";

}

}

#

# Not in a literal block (or just dropped out)

#

if (! $in_literal) {

$block .= $line . "\n";

if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {

$in_literal = 1;

$litprefix = "";

$output .= highlight_block($block);

$block = ""

}

}

}

if ($block) {

$output .= highlight_block($block);

}

foreach $line (split "\n", $output) {

print $lineprefix . $line . "\n";

}

}

sub output_function_rst(%) {

my %args = %{$_[0]};

my ($parameter, $section);

my $oldprefix = $lineprefix;

my $start = "";

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

}

if ($args{'functiontype'} ne "") {

$start .= $args{'functiontype'} . " " . $args{'function'} . " (";

} else {

$start .= $args{'function'} . " (";

}

print $start;

my $count = 0;

foreach my $parameter (@{$args{'parameterlist'}}) {

if ($count ne 0) {

print ", ";

}

$count++;

$type = $args{'parametertypes'}{$parameter};

if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {

# pointer-to-function

print $1 . $parameter . ") (" . $2;

} else {

print $type . " " . $parameter;

}

}

if ($args{'typedef'}) {

print ");``\n\n";

} else {

print ")\n\n";

print_lineno($declaration_start_line);

$lineprefix = " ";

output_highlight_rst($args{'purpose'});

print "\n";

}

print "**Parameters**\n\n";

$lineprefix = " ";

foreach $parameter (@{$args{'parameterlist'}}) {

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

$type = $args{'parametertypes'}{$parameter};

if ($type ne "") {

print "``$type $parameter``\n";

} else {

print "``$parameter``\n";

}

print_lineno($parameterdesc_start_lines{$parameter_name});

if (defined($args{'parameterdescs'}{$parameter_name}) &&

$args{'parameterdescs'}{$parameter_name} ne $undescribed) {

output_highlight_rst($args{'parameterdescs'}{$parameter_name});

} else {

print " *undescribed*\n";

}

print "\n";

}

$lineprefix = $oldprefix;

output_section_rst(@_);

}

sub output_section_rst(%) {

my %args = %{$_[0]};

my $section;

my $oldprefix = $lineprefix;

$lineprefix = "";

foreach $section (@{$args{'sectionlist'}}) {

print "**$section**\n\n";

print_lineno($section_start_lines{$section});

output_highlight_rst($args{'sections'}{$section});

print "\n";

}

print "\n";

$lineprefix = $oldprefix;

}

sub output_enum_rst(%) {

my %args = %{$_[0]};

my ($parameter);

my $oldprefix = $lineprefix;

my $count;

my $name = "enum " . $args{'enum'};

print "\n\n.. c:type:: " . $name . "\n\n";

print_lineno($declaration_start_line);

$lineprefix = " ";

output_highlight_rst($args{'purpose'});

print "\n";

print "**Constants**\n\n";

$lineprefix = " ";

foreach $parameter (@{$args{'parameterlist'}}) {

print "``$parameter``\n";

if ($args{'parameterdescs'}{$parameter} ne $undescribed) {

output_highlight_rst($args{'parameterdescs'}{$parameter});

} else {

print " *undescribed*\n";

}

print "\n";

}

$lineprefix = $oldprefix;

output_section_rst(@_);

}

sub output_typedef_rst(%) {

my %args = %{$_[0]};

my ($parameter);

my $oldprefix = $lineprefix;

my $name = "typedef " . $args{'typedef'};

print "\n\n.. c:type:: " . $name . "\n\n";

print_lineno($declaration_start_line);

$lineprefix = " ";

output_highlight_rst($args{'purpose'});

print "\n";

$lineprefix = $oldprefix;

output_section_rst(@_);

}

sub output_struct_rst(%) {

my %args = %{$_[0]};

my ($parameter);

my $oldprefix = $lineprefix;

my $name = $args{'type'} . " " . $args{'struct'};

print "\n\n.. c:type:: " . $name . "\n\n";

print_lineno($declaration_start_line);

$lineprefix = " ";

output_highlight_rst($args{'purpose'});

print "\n";

print "**Definition**\n\n";

print "::\n\n";

my $declaration = $args{'definition'};

$declaration =~ s/\t/ /g;

print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";

print "**Members**\n\n";

$lineprefix = " ";

foreach $parameter (@{$args{'parameterlist'}}) {

($parameter =~ /^#/) && next;

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

$type = $args{'parametertypes'}{$parameter};

print_lineno($parameterdesc_start_lines{$parameter_name});

print "``" . $parameter . "``\n";

output_highlight_rst($args{'parameterdescs'}{$parameter_name});

print "\n";

}

print "\n";

$lineprefix = $oldprefix;

output_section_rst(@_);

}

## none mode output functions