kernel-doc (fadc0b31cba0bb56bce1a3259cc60e4d7ee67333) kernel-doc (c0d1b6ee780ab16f16cdbe046aa9c83a2a31f9e2)
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

--- 41 unchanged lines hidden (view full) ---

50Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
51
52Output format selection (mutually exclusive):
53 -docbook Output DocBook format.
54 -html Output HTML format.
55 -html5 Output HTML5 format.
56 -list Output symbol list format. This is for use by docproc.
57 -man Output troff manual page format. This is the default.
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

--- 41 unchanged lines hidden (view full) ---

50Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
51
52Output format selection (mutually exclusive):
53 -docbook Output DocBook format.
54 -html Output HTML format.
55 -html5 Output HTML5 format.
56 -list Output symbol list format. This is for use by docproc.
57 -man Output troff manual page format. This is the default.
58 -rst Output reStructuredText format.
58 -text Output plain text format.
59
60Output selection (mutually exclusive):
61 -function NAME Only output documentation for the given function(s)
62 or DOC: section title(s). All other functions and DOC:
63 sections are ignored. May be specified multiple times.
64 -nofunction NAME Do NOT output documentation for the given function(s);
65 only output documentation for the other functions and

--- 132 unchanged lines hidden (view full) ---

198
199# match expressions used to find embedded type information
200my $type_constant = '\%([-_\w]+)';
201my $type_func = '(\w+)\(\)';
202my $type_param = '\@(\w+)';
203my $type_struct = '\&((struct\s*)*[_\w]+)';
204my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
205my $type_env = '(\$\w+)';
59 -text Output plain text format.
60
61Output selection (mutually exclusive):
62 -function NAME Only output documentation for the given function(s)
63 or DOC: section title(s). All other functions and DOC:
64 sections are ignored. May be specified multiple times.
65 -nofunction NAME Do NOT output documentation for the given function(s);
66 only output documentation for the other functions and

--- 132 unchanged lines hidden (view full) ---

199
200# match expressions used to find embedded type information
201my $type_constant = '\%([-_\w]+)';
202my $type_func = '(\w+)\(\)';
203my $type_param = '\@(\w+)';
204my $type_struct = '\&((struct\s*)*[_\w]+)';
205my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
206my $type_env = '(\$\w+)';
207my $type_enum_full = '\&(enum)\s*([_\w]+)';
208my $type_struct_full = '\&(struct)\s*([_\w]+)';
206
207# Output conversion substitutions.
208# One for each output format
209
210# these work fairly well
211my @highlights_html = (
212 [$type_constant, "<i>\$1</i>"],
213 [$type_func, "<b>\$1</b>"],

--- 49 unchanged lines hidden (view full) ---

263my @highlights_text = (
264 [$type_constant, "\$1"],
265 [$type_func, "\$1"],
266 [$type_struct, "\$1"],
267 [$type_param, "\$1"]
268 );
269my $blankline_text = "";
270
209
210# Output conversion substitutions.
211# One for each output format
212
213# these work fairly well
214my @highlights_html = (
215 [$type_constant, "<i>\$1</i>"],
216 [$type_func, "<b>\$1</b>"],

--- 49 unchanged lines hidden (view full) ---

266my @highlights_text = (
267 [$type_constant, "\$1"],
268 [$type_func, "\$1"],
269 [$type_struct, "\$1"],
270 [$type_param, "\$1"]
271 );
272my $blankline_text = "";
273
274# rst-mode
275my @highlights_rst = (
276 [$type_constant, "``\$1``"],
277 [$type_func, "\\:c\\:func\\:`\$1`"],
278 [$type_struct_full, "\\:ref\\:`\$1 \$2`"],
279 [$type_enum_full, "\\:ref\\:`\$1 \$2`"],
280 [$type_struct, "\\:ref\\:`struct \$1`"],
281 [$type_param, "**\$1**"]
282 );
283my $blankline_rst = "\n";
284
271# list mode
272my @highlights_list = (
273 [$type_constant, "\$1"],
274 [$type_func, "\$1"],
275 [$type_struct, "\$1"],
276 [$type_param, "\$1"]
277 );
278my $blankline_list = "";

--- 120 unchanged lines hidden (view full) ---

399 } elsif ($cmd eq "-man") {
400 $output_mode = "man";
401 @highlights = @highlights_man;
402 $blankline = $blankline_man;
403 } elsif ($cmd eq "-text") {
404 $output_mode = "text";
405 @highlights = @highlights_text;
406 $blankline = $blankline_text;
285# list mode
286my @highlights_list = (
287 [$type_constant, "\$1"],
288 [$type_func, "\$1"],
289 [$type_struct, "\$1"],
290 [$type_param, "\$1"]
291 );
292my $blankline_list = "";

--- 120 unchanged lines hidden (view full) ---

413 } elsif ($cmd eq "-man") {
414 $output_mode = "man";
415 @highlights = @highlights_man;
416 $blankline = $blankline_man;
417 } elsif ($cmd eq "-text") {
418 $output_mode = "text";
419 @highlights = @highlights_text;
420 $blankline = $blankline_text;
421 } elsif ($cmd eq "-rst") {
422 $output_mode = "rst";
423 @highlights = @highlights_rst;
424 $blankline = $blankline_rst;
407 } elsif ($cmd eq "-docbook") {
408 $output_mode = "xml";
409 @highlights = @highlights_xml;
410 $blankline = $blankline_xml;
411 } elsif ($cmd eq "-list") {
412 $output_mode = "list";
413 @highlights = @highlights_list;
414 $blankline = $blankline_list;

--- 1284 unchanged lines hidden (view full) ---

1699
1700 foreach $section (@{$args{'sectionlist'}}) {
1701 print " $section:\n";
1702 print " -> ";
1703 output_highlight($args{'sections'}{$section});
1704 }
1705}
1706
425 } elsif ($cmd eq "-docbook") {
426 $output_mode = "xml";
427 @highlights = @highlights_xml;
428 $blankline = $blankline_xml;
429 } elsif ($cmd eq "-list") {
430 $output_mode = "list";
431 @highlights = @highlights_list;
432 $blankline = $blankline_list;

--- 1284 unchanged lines hidden (view full) ---

1717
1718 foreach $section (@{$args{'sectionlist'}}) {
1719 print " $section:\n";
1720 print " -> ";
1721 output_highlight($args{'sections'}{$section});
1722 }
1723}
1724
1725##
1726# output in restructured text
1727#
1728
1729#
1730# This could use some work; it's used to output the DOC: sections, and
1731# starts by putting out the name of the doc section itself, but that tends
1732# to duplicate a header already in the template file.
1733#
1734sub output_blockhead_rst(%) {
1735 my %args = %{$_[0]};
1736 my ($parameter, $section);
1737
1738 foreach $section (@{$args{'sectionlist'}}) {
1739 print "**$section**\n\n";
1740 output_highlight_rst($args{'sections'}{$section});
1741 print "\n";
1742 }
1743}
1744
1745sub output_highlight_rst {
1746 my $contents = join "\n",@_;
1747 my $line;
1748
1749 # undo the evil effects of xml_escape() earlier
1750 $contents = xml_unescape($contents);
1751
1752 eval $dohighlight;
1753 die $@ if $@;
1754
1755 foreach $line (split "\n", $contents) {
1756 if ($line eq "") {
1757 print $lineprefix, $blankline;
1758 } else {
1759 $line =~ s/\\\\\\/\&/g;
1760 print $lineprefix, $line;
1761 }
1762 print "\n";
1763 }
1764}
1765
1766sub output_function_rst(%) {
1767 my %args = %{$_[0]};
1768 my ($parameter, $section);
1769 my $start;
1770
1771 print ".. c:function:: ";
1772 if ($args{'functiontype'} ne "") {
1773 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1774 } else {
1775 $start = $args{'function'} . " (";
1776 }
1777 print $start;
1778
1779 my $count = 0;
1780 foreach my $parameter (@{$args{'parameterlist'}}) {
1781 if ($count ne 0) {
1782 print ", ";
1783 }
1784 $count++;
1785 $type = $args{'parametertypes'}{$parameter};
1786 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1787 # pointer-to-function
1788 print $1 . $parameter . ") (" . $2;
1789 } else {
1790 print $type . " " . $parameter;
1791 }
1792 }
1793 print ")\n\n " . $args{'purpose'} . "\n\n";
1794
1795 print ":Parameters:\n\n";
1796 foreach $parameter (@{$args{'parameterlist'}}) {
1797 my $parameter_name = $parameter;
1798 #$parameter_name =~ s/\[.*//;
1799 $type = $args{'parametertypes'}{$parameter};
1800
1801 if ($type ne "") {
1802 print " ``$type $parameter``\n";
1803 } else {
1804 print " ``$parameter``\n";
1805 }
1806 if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1807 my $oldprefix = $lineprefix;
1808 $lineprefix = " ";
1809 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1810 $lineprefix = $oldprefix;
1811 } else {
1812 print "\n _undescribed_\n";
1813 }
1814 print "\n";
1815 }
1816 output_section_rst(@_);
1817}
1818
1819sub output_section_rst(%) {
1820 my %args = %{$_[0]};
1821 my $section;
1822 my $oldprefix = $lineprefix;
1823 $lineprefix = " ";
1824
1825 foreach $section (@{$args{'sectionlist'}}) {
1826 print ":$section:\n\n";
1827 output_highlight_rst($args{'sections'}{$section});
1828 print "\n";
1829 }
1830 print "\n";
1831 $lineprefix = $oldprefix;
1832}
1833
1834sub output_enum_rst(%) {
1835 my %args = %{$_[0]};
1836 my ($parameter);
1837 my $count;
1838
1839 my $name = "enum " . $args{'enum'};
1840 print ".. _" . $name . ":\n\n";
1841 print "**$name**\n\n";
1842 print " " . $args{'purpose'} . "\n\n";
1843
1844 print "..\n\n:Constants:\n\n";
1845 my $oldprefix = $lineprefix;
1846 $lineprefix = " ";
1847 foreach $parameter (@{$args{'parameterlist'}}) {
1848 print " `$parameter`\n";
1849 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1850 output_highlight_rst($args{'parameterdescs'}{$parameter});
1851 } else {
1852 print " undescribed\n";
1853 }
1854 print "\n";
1855 }
1856 $lineprefix = $oldprefix;
1857 output_section_rst(@_);
1858}
1859
1860sub output_typedef_rst(%) {
1861 my %args = %{$_[0]};
1862 my ($parameter);
1863 my $count;
1864 my $name = "typedef " . $args{'typedef'};
1865
1866 print "**$name**\n\n";
1867 print $args{'purpose'} . "\n\n";
1868
1869 output_section_rst(@_);
1870}
1871
1872sub output_struct_rst(%) {
1873 my %args = %{$_[0]};
1874 my ($parameter);
1875 my $name = $args{'type'} . " " . $args{'struct'};
1876
1877 print ".. _" . $name . ":\n\n";
1878 print "**$name**\n\n";
1879 print " " . $args{'purpose'} . "\n\n";
1880
1881 print ":Definition:\n\n";
1882 print " ::\n\n";
1883 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1884 foreach $parameter (@{$args{'parameterlist'}}) {
1885 if ($parameter =~ /^#/) {
1886 print " " . "$parameter\n";
1887 next;
1888 }
1889
1890 my $parameter_name = $parameter;
1891 $parameter_name =~ s/\[.*//;
1892
1893 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1894 $type = $args{'parametertypes'}{$parameter};
1895 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1896 # pointer-to-function
1897 print " $1 $parameter) ($2);\n";
1898 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1899 # bitfield
1900 print " $1 $parameter$2;\n";
1901 } else {
1902 print " " . $type . " " . $parameter . ";\n";
1903 }
1904 }
1905 print " };\n\n";
1906
1907 print ":Members:\n\n";
1908 foreach $parameter (@{$args{'parameterlist'}}) {
1909 ($parameter =~ /^#/) && next;
1910
1911 my $parameter_name = $parameter;
1912 $parameter_name =~ s/\[.*//;
1913
1914 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1915 $type = $args{'parametertypes'}{$parameter};
1916 print " `$type $parameter`" . "\n";
1917 my $oldprefix = $lineprefix;
1918 $lineprefix = " ";
1919 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1920 $lineprefix = $oldprefix;
1921 print "\n";
1922 }
1923 print "\n";
1924 output_section_rst(@_);
1925}
1926
1927
1707## list mode output functions
1708
1709sub output_function_list(%) {
1710 my %args = %{$_[0]};
1711
1712 print $args{'function'} . "\n";
1713}
1714

--- 685 unchanged lines hidden (view full) ---

2400 return $text;
2401 }
2402 $text =~ s/\&/\\\\\\amp;/g;
2403 $text =~ s/\</\\\\\\lt;/g;
2404 $text =~ s/\>/\\\\\\gt;/g;
2405 return $text;
2406}
2407
1928## list mode output functions
1929
1930sub output_function_list(%) {
1931 my %args = %{$_[0]};
1932
1933 print $args{'function'} . "\n";
1934}
1935

--- 685 unchanged lines hidden (view full) ---

2621 return $text;
2622 }
2623 $text =~ s/\&/\\\\\\amp;/g;
2624 $text =~ s/\</\\\\\\lt;/g;
2625 $text =~ s/\>/\\\\\\gt;/g;
2626 return $text;
2627}
2628
2629# xml_unescape: reverse the effects of xml_escape
2630sub xml_unescape($) {
2631 my $text = shift;
2632 if (($output_mode eq "text") || ($output_mode eq "man")) {
2633 return $text;
2634 }
2635 $text =~ s/\\\\\\amp;/\&/g;
2636 $text =~ s/\\\\\\lt;/</g;
2637 $text =~ s/\\\\\\gt;/>/g;
2638 return $text;
2639}
2640
2408# convert local escape strings to html
2409# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2410sub local_unescape($) {
2411 my $text = shift;
2412 if (($output_mode eq "text") || ($output_mode eq "man")) {
2413 return $text;
2414 }
2415 $text =~ s/\\\\\\\\lt:/</g;

--- 324 unchanged lines hidden --- 		2641# convert local escape strings to html
2642# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2643sub local_unescape($) {
2644 my $text = shift;
2645 if (($output_mode eq "text") || ($output_mode eq "man")) {
2646 return $text;
2647 }
2648 $text =~ s/\\\\\\\\lt:/</g;

--- 324 unchanged lines hidden ---