mirror of
https://github.com/torvalds/linux.git
synced 2024-11-27 14:41:39 +00:00
kernel-doc: produce RestructuredText output
If given the -rst flag, output will now be in RestructuredText. Various glitches to be worked out yet. In the end I decided not to use RST section headings within the kerneldoc comments. gpu.tmpl already has headings five levels deep; adding more is not going to bring clarity. This is really just Jani Nikula's asciidoc change with the serial numbers filed off. It's a hack job that doubtless needs a lot of cleaning up. Signed-off-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet
parent
fadc0b31cb
commit
c0d1b6ee78
@ -55,6 +55,7 @@ Output format selection (mutually exclusive):
|
||||
-html5 Output HTML5 format.
|
||||
-list Output symbol list format. This is for use by docproc.
|
||||
-man Output troff manual page format. This is the default.
|
||||
-rst Output reStructuredText format.
|
||||
-text Output plain text format.
|
||||
|
||||
Output selection (mutually exclusive):
|
||||
@ -203,6 +204,8 @@ my $type_param = '\@(\w+)';
|
||||
my $type_struct = '\&((struct\s*)*[_\w]+)';
|
||||
my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
|
||||
my $type_env = '(\$\w+)';
|
||||
my $type_enum_full = '\&(enum)\s*([_\w]+)';
|
||||
my $type_struct_full = '\&(struct)\s*([_\w]+)';
|
||||
|
||||
# Output conversion substitutions.
|
||||
# One for each output format
|
||||
@ -268,6 +271,17 @@ my @highlights_text = (
|
||||
);
|
||||
my $blankline_text = "";
|
||||
|
||||
# rst-mode
|
||||
my @highlights_rst = (
|
||||
[$type_constant, "``\$1``"],
|
||||
[$type_func, "\\:c\\:func\\:`\$1`"],
|
||||
[$type_struct_full, "\\:ref\\:`\$1 \$2`"],
|
||||
[$type_enum_full, "\\:ref\\:`\$1 \$2`"],
|
||||
[$type_struct, "\\:ref\\:`struct \$1`"],
|
||||
[$type_param, "**\$1**"]
|
||||
);
|
||||
my $blankline_rst = "\n";
|
||||
|
||||
# list mode
|
||||
my @highlights_list = (
|
||||
[$type_constant, "\$1"],
|
||||
@ -404,6 +418,10 @@ while ($ARGV[0] =~ m/^-(.*)/) {
|
||||
$output_mode = "text";
|
||||
@highlights = @highlights_text;
|
||||
$blankline = $blankline_text;
|
||||
} elsif ($cmd eq "-rst") {
|
||||
$output_mode = "rst";
|
||||
@highlights = @highlights_rst;
|
||||
$blankline = $blankline_rst;
|
||||
} elsif ($cmd eq "-docbook") {
|
||||
$output_mode = "xml";
|
||||
@highlights = @highlights_xml;
|
||||
@ -1704,6 +1722,209 @@ sub output_blockhead_text(%) {
|
||||
}
|
||||
}
|
||||
|
||||
##
|
||||
# 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'}}) {
|
||||
print "**$section**\n\n";
|
||||
output_highlight_rst($args{'sections'}{$section});
|
||||
print "\n";
|
||||
}
|
||||
}
|
||||
|
||||
sub output_highlight_rst {
|
||||
my $contents = join "\n",@_;
|
||||
my $line;
|
||||
|
||||
# undo the evil effects of xml_escape() earlier
|
||||
$contents = xml_unescape($contents);
|
||||
|
||||
eval $dohighlight;
|
||||
die $@ if $@;
|
||||
|
||||
foreach $line (split "\n", $contents) {
|
||||
if ($line eq "") {
|
||||
print $lineprefix, $blankline;
|
||||
} else {
|
||||
$line =~ s/\\\\\\/\&/g;
|
||||
print $lineprefix, $line;
|
||||
}
|
||||
print "\n";
|
||||
}
|
||||
}
|
||||
|
||||
sub output_function_rst(%) {
|
||||
my %args = %{$_[0]};
|
||||
my ($parameter, $section);
|
||||
my $start;
|
||||
|
||||
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;
|
||||
}
|
||||
}
|
||||
print ")\n\n " . $args{'purpose'} . "\n\n";
|
||||
|
||||
print ":Parameters:\n\n";
|
||||
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";
|
||||
}
|
||||
if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
|
||||
my $oldprefix = $lineprefix;
|
||||
$lineprefix = " ";
|
||||
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
|
||||
$lineprefix = $oldprefix;
|
||||
} else {
|
||||
print "\n _undescribed_\n";
|
||||
}
|
||||
print "\n";
|
||||
}
|
||||
output_section_rst(@_);
|
||||
}
|
||||
|
||||
sub output_section_rst(%) {
|
||||
my %args = %{$_[0]};
|
||||
my $section;
|
||||
my $oldprefix = $lineprefix;
|
||||
$lineprefix = " ";
|
||||
|
||||
foreach $section (@{$args{'sectionlist'}}) {
|
||||
print ":$section:\n\n";
|
||||
output_highlight_rst($args{'sections'}{$section});
|
||||
print "\n";
|
||||
}
|
||||
print "\n";
|
||||
$lineprefix = $oldprefix;
|
||||
}
|
||||
|
||||
sub output_enum_rst(%) {
|
||||
my %args = %{$_[0]};
|
||||
my ($parameter);
|
||||
my $count;
|
||||
|
||||
my $name = "enum " . $args{'enum'};
|
||||
print ".. _" . $name . ":\n\n";
|
||||
print "**$name**\n\n";
|
||||
print " " . $args{'purpose'} . "\n\n";
|
||||
|
||||
print "..\n\n:Constants:\n\n";
|
||||
my $oldprefix = $lineprefix;
|
||||
$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 $count;
|
||||
my $name = "typedef " . $args{'typedef'};
|
||||
|
||||
print "**$name**\n\n";
|
||||
print $args{'purpose'} . "\n\n";
|
||||
|
||||
output_section_rst(@_);
|
||||
}
|
||||
|
||||
sub output_struct_rst(%) {
|
||||
my %args = %{$_[0]};
|
||||
my ($parameter);
|
||||
my $name = $args{'type'} . " " . $args{'struct'};
|
||||
|
||||
print ".. _" . $name . ":\n\n";
|
||||
print "**$name**\n\n";
|
||||
print " " . $args{'purpose'} . "\n\n";
|
||||
|
||||
print ":Definition:\n\n";
|
||||
print " ::\n\n";
|
||||
print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
|
||||
foreach $parameter (@{$args{'parameterlist'}}) {
|
||||
if ($parameter =~ /^#/) {
|
||||
print " " . "$parameter\n";
|
||||
next;
|
||||
}
|
||||
|
||||
my $parameter_name = $parameter;
|
||||
$parameter_name =~ s/\[.*//;
|
||||
|
||||
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
|
||||
$type = $args{'parametertypes'}{$parameter};
|
||||
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
|
||||
# pointer-to-function
|
||||
print " $1 $parameter) ($2);\n";
|
||||
} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
|
||||
# bitfield
|
||||
print " $1 $parameter$2;\n";
|
||||
} else {
|
||||
print " " . $type . " " . $parameter . ";\n";
|
||||
}
|
||||
}
|
||||
print " };\n\n";
|
||||
|
||||
print ":Members:\n\n";
|
||||
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 " `$type $parameter`" . "\n";
|
||||
my $oldprefix = $lineprefix;
|
||||
$lineprefix = " ";
|
||||
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
|
||||
$lineprefix = $oldprefix;
|
||||
print "\n";
|
||||
}
|
||||
print "\n";
|
||||
output_section_rst(@_);
|
||||
}
|
||||
|
||||
|
||||
## list mode output functions
|
||||
|
||||
sub output_function_list(%) {
|
||||
@ -2405,6 +2626,18 @@ sub xml_escape($) {
|
||||
return $text;
|
||||
}
|
||||
|
||||
# xml_unescape: reverse the effects of xml_escape
|
||||
sub xml_unescape($) {
|
||||
my $text = shift;
|
||||
if (($output_mode eq "text") || ($output_mode eq "man")) {
|
||||
return $text;
|
||||
}
|
||||
$text =~ s/\\\\\\amp;/\&/g;
|
||||
$text =~ s/\\\\\\lt;/</g;
|
||||
$text =~ s/\\\\\\gt;/>/g;
|
||||
return $text;
|
||||
}
|
||||
|
||||
# convert local escape strings to html
|
||||
# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
|
||||
sub local_unescape($) {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user