PageRenderTime 59ms CodeModel.GetById 17ms RepoModel.GetById 0ms app.codeStats 0ms

/scripts/kernel-doc

https://bitbucket.org/bradfa/linux
Perl | 2604 lines | 2212 code | 143 blank | 249 comment | 92 complexity | a47c3bce17be14ce657a6b30b0d6a0e7 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.0, AGPL-1.0

Large files files are truncated, but you can click here to view the full file

  1. #!/usr/bin/perl -w
  2. use strict;
  3. ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
  4. ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
  5. ## Copyright (C) 2001 Simon Huggins ##
  6. ## Copyright (C) 2005-2012 Randy Dunlap ##
  7. ## Copyright (C) 2012 Dan Luedtke ##
  8. ## ##
  9. ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
  10. ## Copyright (c) 2000 MontaVista Software, Inc. ##
  11. ## ##
  12. ## This software falls under the GNU General Public License. ##
  13. ## Please read the COPYING file for more information ##
  14. # 18/01/2001 - Cleanups
  15. # Functions prototyped as foo(void) same as foo()
  16. # Stop eval'ing where we don't need to.
  17. # -- huggie@earth.li
  18. # 27/06/2001 - Allowed whitespace after initial "/**" and
  19. # allowed comments before function declarations.
  20. # -- Christian Kreibich <ck@whoop.org>
  21. # Still to do:
  22. # - add perldoc documentation
  23. # - Look more closely at some of the scarier bits :)
  24. # 26/05/2001 - Support for separate source and object trees.
  25. # Return error code.
  26. # Keith Owens <kaos@ocs.com.au>
  27. # 23/09/2001 - Added support for typedefs, structs, enums and unions
  28. # Support for Context section; can be terminated using empty line
  29. # Small fixes (like spaces vs. \s in regex)
  30. # -- Tim Jansen <tim@tjansen.de>
  31. # 25/07/2012 - Added support for HTML5
  32. # -- Dan Luedtke <mail@danrl.de>
  33. #
  34. # This will read a 'c' file and scan for embedded comments in the
  35. # style of gnome comments (+minor extensions - see below).
  36. #
  37. # Note: This only supports 'c'.
  38. # usage:
  39. # kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  40. # [ -no-doc-sections ]
  41. # [ -function funcname [ -function funcname ...] ]
  42. # c file(s)s > outputfile
  43. # or
  44. # [ -nofunction funcname [ -function funcname ...] ]
  45. # c file(s)s > outputfile
  46. #
  47. # Set output format using one of -docbook -html -html5 -text or -man.
  48. # Default is man.
  49. # The -list format is for internal use by docproc.
  50. #
  51. # -no-doc-sections
  52. # Do not output DOC: sections
  53. #
  54. # -function funcname
  55. # If set, then only generate documentation for the given function(s) or
  56. # DOC: section titles. All other functions and DOC: sections are ignored.
  57. #
  58. # -nofunction funcname
  59. # If set, then only generate documentation for the other function(s)/DOC:
  60. # sections. Cannot be used together with -function (yes, that's a bug --
  61. # perl hackers can fix it 8))
  62. #
  63. # c files - list of 'c' files to process
  64. #
  65. # All output goes to stdout, with errors to stderr.
  66. #
  67. # format of comments.
  68. # In the following table, (...)? signifies optional structure.
  69. # (...)* signifies 0 or more structure elements
  70. # /**
  71. # * function_name(:)? (- short description)?
  72. # (* @parameterx: (description of parameter x)?)*
  73. # (* a blank line)?
  74. # * (Description:)? (Description of function)?
  75. # * (section header: (section description)? )*
  76. # (*)?*/
  77. #
  78. # So .. the trivial example would be:
  79. #
  80. # /**
  81. # * my_function
  82. # */
  83. #
  84. # If the Description: header tag is omitted, then there must be a blank line
  85. # after the last parameter specification.
  86. # e.g.
  87. # /**
  88. # * my_function - does my stuff
  89. # * @my_arg: its mine damnit
  90. # *
  91. # * Does my stuff explained.
  92. # */
  93. #
  94. # or, could also use:
  95. # /**
  96. # * my_function - does my stuff
  97. # * @my_arg: its mine damnit
  98. # * Description: Does my stuff explained.
  99. # */
  100. # etc.
  101. #
  102. # Besides functions you can also write documentation for structs, unions,
  103. # enums and typedefs. Instead of the function name you must write the name
  104. # of the declaration; the struct/union/enum/typedef must always precede
  105. # the name. Nesting of declarations is not supported.
  106. # Use the argument mechanism to document members or constants.
  107. # e.g.
  108. # /**
  109. # * struct my_struct - short description
  110. # * @a: first member
  111. # * @b: second member
  112. # *
  113. # * Longer description
  114. # */
  115. # struct my_struct {
  116. # int a;
  117. # int b;
  118. # /* private: */
  119. # int c;
  120. # };
  121. #
  122. # All descriptions can be multiline, except the short function description.
  123. #
  124. # You can also add additional sections. When documenting kernel functions you
  125. # should document the "Context:" of the function, e.g. whether the functions
  126. # can be called form interrupts. Unlike other sections you can end it with an
  127. # empty line.
  128. # A non-void function should have a "Return:" section describing the return
  129. # value(s).
  130. # Example-sections should contain the string EXAMPLE so that they are marked
  131. # appropriately in DocBook.
  132. #
  133. # Example:
  134. # /**
  135. # * user_function - function that can only be called in user context
  136. # * @a: some argument
  137. # * Context: !in_interrupt()
  138. # *
  139. # * Some description
  140. # * Example:
  141. # * user_function(22);
  142. # */
  143. # ...
  144. #
  145. #
  146. # All descriptive text is further processed, scanning for the following special
  147. # patterns, which are highlighted appropriately.
  148. #
  149. # 'funcname()' - function
  150. # '$ENVVAR' - environmental variable
  151. # '&struct_name' - name of a structure (up to two words including 'struct')
  152. # '@parameter' - name of a parameter
  153. # '%CONST' - name of a constant.
  154. ## init lots of data
  155. my $errors = 0;
  156. my $warnings = 0;
  157. my $anon_struct_union = 0;
  158. # match expressions used to find embedded type information
  159. my $type_constant = '\%([-_\w]+)';
  160. my $type_func = '(\w+)\(\)';
  161. my $type_param = '\@(\w+)';
  162. my $type_struct = '\&((struct\s*)*[_\w]+)';
  163. my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
  164. my $type_env = '(\$\w+)';
  165. # Output conversion substitutions.
  166. # One for each output format
  167. # these work fairly well
  168. my %highlights_html = ( $type_constant, "<i>\$1</i>",
  169. $type_func, "<b>\$1</b>",
  170. $type_struct_xml, "<i>\$1</i>",
  171. $type_env, "<b><i>\$1</i></b>",
  172. $type_param, "<tt><b>\$1</b></tt>" );
  173. my $local_lt = "\\\\\\\\lt:";
  174. my $local_gt = "\\\\\\\\gt:";
  175. my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
  176. # html version 5
  177. my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
  178. $type_func, "<span class=\"func\">\$1</span>",
  179. $type_struct_xml, "<span class=\"struct\">\$1</span>",
  180. $type_env, "<span class=\"env\">\$1</span>",
  181. $type_param, "<span class=\"param\">\$1</span>" );
  182. my $blankline_html5 = $local_lt . "br /" . $local_gt;
  183. # XML, docbook format
  184. my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
  185. $type_constant, "<constant>\$1</constant>",
  186. $type_func, "<function>\$1</function>",
  187. $type_struct_xml, "<structname>\$1</structname>",
  188. $type_env, "<envar>\$1</envar>",
  189. $type_param, "<parameter>\$1</parameter>" );
  190. my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
  191. # gnome, docbook format
  192. my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
  193. $type_func, "<function>\$1</function>",
  194. $type_struct, "<structname>\$1</structname>",
  195. $type_env, "<envar>\$1</envar>",
  196. $type_param, "<parameter>\$1</parameter>" );
  197. my $blankline_gnome = "</para><para>\n";
  198. # these are pretty rough
  199. my %highlights_man = ( $type_constant, "\$1",
  200. $type_func, "\\\\fB\$1\\\\fP",
  201. $type_struct, "\\\\fI\$1\\\\fP",
  202. $type_param, "\\\\fI\$1\\\\fP" );
  203. my $blankline_man = "";
  204. # text-mode
  205. my %highlights_text = ( $type_constant, "\$1",
  206. $type_func, "\$1",
  207. $type_struct, "\$1",
  208. $type_param, "\$1" );
  209. my $blankline_text = "";
  210. # list mode
  211. my %highlights_list = ( $type_constant, "\$1",
  212. $type_func, "\$1",
  213. $type_struct, "\$1",
  214. $type_param, "\$1" );
  215. my $blankline_list = "";
  216. # read arguments
  217. if ($#ARGV == -1) {
  218. usage();
  219. }
  220. my $kernelversion;
  221. my $dohighlight = "";
  222. my $verbose = 0;
  223. my $output_mode = "man";
  224. my $output_preformatted = 0;
  225. my $no_doc_sections = 0;
  226. my %highlights = %highlights_man;
  227. my $blankline = $blankline_man;
  228. my $modulename = "Kernel API";
  229. my $function_only = 0;
  230. my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
  231. 'July', 'August', 'September', 'October',
  232. 'November', 'December')[(localtime)[4]] .
  233. " " . ((localtime)[5]+1900);
  234. # Essentially these are globals.
  235. # They probably want to be tidied up, made more localised or something.
  236. # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
  237. # could cause "use of undefined value" or other bugs.
  238. my ($function, %function_table, %parametertypes, $declaration_purpose);
  239. my ($type, $declaration_name, $return_type);
  240. my ($newsection, $newcontents, $prototype, $brcount, %source_map);
  241. if (defined($ENV{'KBUILD_VERBOSE'})) {
  242. $verbose = "$ENV{'KBUILD_VERBOSE'}";
  243. }
  244. # Generated docbook code is inserted in a template at a point where
  245. # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
  246. # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
  247. # We keep track of number of generated entries and generate a dummy
  248. # if needs be to ensure the expanded template can be postprocessed
  249. # into html.
  250. my $section_counter = 0;
  251. my $lineprefix="";
  252. # states
  253. # 0 - normal code
  254. # 1 - looking for function name
  255. # 2 - scanning field start.
  256. # 3 - scanning prototype.
  257. # 4 - documentation block
  258. my $state;
  259. my $in_doc_sect;
  260. #declaration types: can be
  261. # 'function', 'struct', 'union', 'enum', 'typedef'
  262. my $decl_type;
  263. my $doc_special = "\@\%\$\&";
  264. my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
  265. my $doc_end = '\*/';
  266. my $doc_com = '\s*\*\s*';
  267. my $doc_com_body = '\s*\* ?';
  268. my $doc_decl = $doc_com . '(\w+)';
  269. my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
  270. my $doc_content = $doc_com_body . '(.*)';
  271. my $doc_block = $doc_com . 'DOC:\s*(.*)?';
  272. my %constants;
  273. my %parameterdescs;
  274. my @parameterlist;
  275. my %sections;
  276. my @sectionlist;
  277. my $sectcheck;
  278. my $struct_actual;
  279. my $contents = "";
  280. my $section_default = "Description"; # default section
  281. my $section_intro = "Introduction";
  282. my $section = $section_default;
  283. my $section_context = "Context";
  284. my $section_return = "Return";
  285. my $undescribed = "-- undescribed --";
  286. reset_state();
  287. while ($ARGV[0] =~ m/^-(.*)/) {
  288. my $cmd = shift @ARGV;
  289. if ($cmd eq "-html") {
  290. $output_mode = "html";
  291. %highlights = %highlights_html;
  292. $blankline = $blankline_html;
  293. } elsif ($cmd eq "-html5") {
  294. $output_mode = "html5";
  295. %highlights = %highlights_html5;
  296. $blankline = $blankline_html5;
  297. } elsif ($cmd eq "-man") {
  298. $output_mode = "man";
  299. %highlights = %highlights_man;
  300. $blankline = $blankline_man;
  301. } elsif ($cmd eq "-text") {
  302. $output_mode = "text";
  303. %highlights = %highlights_text;
  304. $blankline = $blankline_text;
  305. } elsif ($cmd eq "-docbook") {
  306. $output_mode = "xml";
  307. %highlights = %highlights_xml;
  308. $blankline = $blankline_xml;
  309. } elsif ($cmd eq "-list") {
  310. $output_mode = "list";
  311. %highlights = %highlights_list;
  312. $blankline = $blankline_list;
  313. } elsif ($cmd eq "-gnome") {
  314. $output_mode = "gnome";
  315. %highlights = %highlights_gnome;
  316. $blankline = $blankline_gnome;
  317. } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
  318. $modulename = shift @ARGV;
  319. } elsif ($cmd eq "-function") { # to only output specific functions
  320. $function_only = 1;
  321. $function = shift @ARGV;
  322. $function_table{$function} = 1;
  323. } elsif ($cmd eq "-nofunction") { # to only output specific functions
  324. $function_only = 2;
  325. $function = shift @ARGV;
  326. $function_table{$function} = 1;
  327. } elsif ($cmd eq "-v") {
  328. $verbose = 1;
  329. } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
  330. usage();
  331. } elsif ($cmd eq '-no-doc-sections') {
  332. $no_doc_sections = 1;
  333. }
  334. }
  335. # continue execution near EOF;
  336. sub usage {
  337. print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n";
  338. print " [ -no-doc-sections ]\n";
  339. print " [ -function funcname [ -function funcname ...] ]\n";
  340. print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
  341. print " [ -v ]\n";
  342. print " c source file(s) > outputfile\n";
  343. print " -v : verbose output, more warnings & other info listed\n";
  344. exit 1;
  345. }
  346. # get kernel version from env
  347. sub get_kernel_version() {
  348. my $version = 'unknown kernel version';
  349. if (defined($ENV{'KERNELVERSION'})) {
  350. $version = $ENV{'KERNELVERSION'};
  351. }
  352. return $version;
  353. }
  354. ##
  355. # dumps section contents to arrays/hashes intended for that purpose.
  356. #
  357. sub dump_section {
  358. my $file = shift;
  359. my $name = shift;
  360. my $contents = join "\n", @_;
  361. if ($name =~ m/$type_constant/) {
  362. $name = $1;
  363. # print STDERR "constant section '$1' = '$contents'\n";
  364. $constants{$name} = $contents;
  365. } elsif ($name =~ m/$type_param/) {
  366. # print STDERR "parameter def '$1' = '$contents'\n";
  367. $name = $1;
  368. $parameterdescs{$name} = $contents;
  369. $sectcheck = $sectcheck . $name . " ";
  370. } elsif ($name eq "@\.\.\.") {
  371. # print STDERR "parameter def '...' = '$contents'\n";
  372. $name = "...";
  373. $parameterdescs{$name} = $contents;
  374. $sectcheck = $sectcheck . $name . " ";
  375. } else {
  376. # print STDERR "other section '$name' = '$contents'\n";
  377. if (defined($sections{$name}) && ($sections{$name} ne "")) {
  378. print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
  379. ++$errors;
  380. }
  381. $sections{$name} = $contents;
  382. push @sectionlist, $name;
  383. }
  384. }
  385. ##
  386. # dump DOC: section after checking that it should go out
  387. #
  388. sub dump_doc_section {
  389. my $file = shift;
  390. my $name = shift;
  391. my $contents = join "\n", @_;
  392. if ($no_doc_sections) {
  393. return;
  394. }
  395. if (($function_only == 0) ||
  396. ( $function_only == 1 && defined($function_table{$name})) ||
  397. ( $function_only == 2 && !defined($function_table{$name})))
  398. {
  399. dump_section($file, $name, $contents);
  400. output_blockhead({'sectionlist' => \@sectionlist,
  401. 'sections' => \%sections,
  402. 'module' => $modulename,
  403. 'content-only' => ($function_only != 0), });
  404. }
  405. }
  406. ##
  407. # output function
  408. #
  409. # parameterdescs, a hash.
  410. # function => "function name"
  411. # parameterlist => @list of parameters
  412. # parameterdescs => %parameter descriptions
  413. # sectionlist => @list of sections
  414. # sections => %section descriptions
  415. #
  416. sub output_highlight {
  417. my $contents = join "\n",@_;
  418. my $line;
  419. # DEBUG
  420. # if (!defined $contents) {
  421. # use Carp;
  422. # confess "output_highlight got called with no args?\n";
  423. # }
  424. if ($output_mode eq "html" || $output_mode eq "html5" ||
  425. $output_mode eq "xml") {
  426. $contents = local_unescape($contents);
  427. # convert data read & converted thru xml_escape() into &xyz; format:
  428. $contents =~ s/\\\\\\/\&/g;
  429. }
  430. # print STDERR "contents b4:$contents\n";
  431. eval $dohighlight;
  432. die $@ if $@;
  433. # print STDERR "contents af:$contents\n";
  434. # strip whitespaces when generating html5
  435. if ($output_mode eq "html5") {
  436. $contents =~ s/^\s+//;
  437. $contents =~ s/\s+$//;
  438. }
  439. foreach $line (split "\n", $contents) {
  440. if (! $output_preformatted) {
  441. $line =~ s/^\s*//;
  442. }
  443. if ($line eq ""){
  444. if (! $output_preformatted) {
  445. print $lineprefix, local_unescape($blankline);
  446. }
  447. } else {
  448. $line =~ s/\\\\\\/\&/g;
  449. if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
  450. print "\\&$line";
  451. } else {
  452. print $lineprefix, $line;
  453. }
  454. }
  455. print "\n";
  456. }
  457. }
  458. # output sections in html
  459. sub output_section_html(%) {
  460. my %args = %{$_[0]};
  461. my $section;
  462. foreach $section (@{$args{'sectionlist'}}) {
  463. print "<h3>$section</h3>\n";
  464. print "<blockquote>\n";
  465. output_highlight($args{'sections'}{$section});
  466. print "</blockquote>\n";
  467. }
  468. }
  469. # output enum in html
  470. sub output_enum_html(%) {
  471. my %args = %{$_[0]};
  472. my ($parameter);
  473. my $count;
  474. print "<h2>enum " . $args{'enum'} . "</h2>\n";
  475. print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
  476. $count = 0;
  477. foreach $parameter (@{$args{'parameterlist'}}) {
  478. print " <b>" . $parameter . "</b>";
  479. if ($count != $#{$args{'parameterlist'}}) {
  480. $count++;
  481. print ",\n";
  482. }
  483. print "<br>";
  484. }
  485. print "};<br>\n";
  486. print "<h3>Constants</h3>\n";
  487. print "<dl>\n";
  488. foreach $parameter (@{$args{'parameterlist'}}) {
  489. print "<dt><b>" . $parameter . "</b>\n";
  490. print "<dd>";
  491. output_highlight($args{'parameterdescs'}{$parameter});
  492. }
  493. print "</dl>\n";
  494. output_section_html(@_);
  495. print "<hr>\n";
  496. }
  497. # output typedef in html
  498. sub output_typedef_html(%) {
  499. my %args = %{$_[0]};
  500. my ($parameter);
  501. my $count;
  502. print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
  503. print "<b>typedef " . $args{'typedef'} . "</b>\n";
  504. output_section_html(@_);
  505. print "<hr>\n";
  506. }
  507. # output struct in html
  508. sub output_struct_html(%) {
  509. my %args = %{$_[0]};
  510. my ($parameter);
  511. print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
  512. print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
  513. foreach $parameter (@{$args{'parameterlist'}}) {
  514. if ($parameter =~ /^#/) {
  515. print "$parameter<br>\n";
  516. next;
  517. }
  518. my $parameter_name = $parameter;
  519. $parameter_name =~ s/\[.*//;
  520. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  521. $type = $args{'parametertypes'}{$parameter};
  522. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  523. # pointer-to-function
  524. print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
  525. } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  526. # bitfield
  527. print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
  528. } else {
  529. print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
  530. }
  531. }
  532. print "};<br>\n";
  533. print "<h3>Members</h3>\n";
  534. print "<dl>\n";
  535. foreach $parameter (@{$args{'parameterlist'}}) {
  536. ($parameter =~ /^#/) && next;
  537. my $parameter_name = $parameter;
  538. $parameter_name =~ s/\[.*//;
  539. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  540. print "<dt><b>" . $parameter . "</b>\n";
  541. print "<dd>";
  542. output_highlight($args{'parameterdescs'}{$parameter_name});
  543. }
  544. print "</dl>\n";
  545. output_section_html(@_);
  546. print "<hr>\n";
  547. }
  548. # output function in html
  549. sub output_function_html(%) {
  550. my %args = %{$_[0]};
  551. my ($parameter, $section);
  552. my $count;
  553. print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
  554. print "<i>" . $args{'functiontype'} . "</i>\n";
  555. print "<b>" . $args{'function'} . "</b>\n";
  556. print "(";
  557. $count = 0;
  558. foreach $parameter (@{$args{'parameterlist'}}) {
  559. $type = $args{'parametertypes'}{$parameter};
  560. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  561. # pointer-to-function
  562. print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
  563. } else {
  564. print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
  565. }
  566. if ($count != $#{$args{'parameterlist'}}) {
  567. $count++;
  568. print ",\n";
  569. }
  570. }
  571. print ")\n";
  572. print "<h3>Arguments</h3>\n";
  573. print "<dl>\n";
  574. foreach $parameter (@{$args{'parameterlist'}}) {
  575. my $parameter_name = $parameter;
  576. $parameter_name =~ s/\[.*//;
  577. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  578. print "<dt><b>" . $parameter . "</b>\n";
  579. print "<dd>";
  580. output_highlight($args{'parameterdescs'}{$parameter_name});
  581. }
  582. print "</dl>\n";
  583. output_section_html(@_);
  584. print "<hr>\n";
  585. }
  586. # output DOC: block header in html
  587. sub output_blockhead_html(%) {
  588. my %args = %{$_[0]};
  589. my ($parameter, $section);
  590. my $count;
  591. foreach $section (@{$args{'sectionlist'}}) {
  592. print "<h3>$section</h3>\n";
  593. print "<ul>\n";
  594. output_highlight($args{'sections'}{$section});
  595. print "</ul>\n";
  596. }
  597. print "<hr>\n";
  598. }
  599. # output sections in html5
  600. sub output_section_html5(%) {
  601. my %args = %{$_[0]};
  602. my $section;
  603. foreach $section (@{$args{'sectionlist'}}) {
  604. print "<section>\n";
  605. print "<h1>$section</h1>\n";
  606. print "<p>\n";
  607. output_highlight($args{'sections'}{$section});
  608. print "</p>\n";
  609. print "</section>\n";
  610. }
  611. }
  612. # output enum in html5
  613. sub output_enum_html5(%) {
  614. my %args = %{$_[0]};
  615. my ($parameter);
  616. my $count;
  617. my $html5id;
  618. $html5id = $args{'enum'};
  619. $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
  620. print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
  621. print "<h1>enum " . $args{'enum'} . "</h1>\n";
  622. print "<ol class=\"code\">\n";
  623. print "<li>";
  624. print "<span class=\"keyword\">enum</span> ";
  625. print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
  626. print "</li>\n";
  627. $count = 0;
  628. foreach $parameter (@{$args{'parameterlist'}}) {
  629. print "<li class=\"indent\">";
  630. print "<span class=\"param\">" . $parameter . "</span>";
  631. if ($count != $#{$args{'parameterlist'}}) {
  632. $count++;
  633. print ",";
  634. }
  635. print "</li>\n";
  636. }
  637. print "<li>};</li>\n";
  638. print "</ol>\n";
  639. print "<section>\n";
  640. print "<h1>Constants</h1>\n";
  641. print "<dl>\n";
  642. foreach $parameter (@{$args{'parameterlist'}}) {
  643. print "<dt>" . $parameter . "</dt>\n";
  644. print "<dd>";
  645. output_highlight($args{'parameterdescs'}{$parameter});
  646. print "</dd>\n";
  647. }
  648. print "</dl>\n";
  649. print "</section>\n";
  650. output_section_html5(@_);
  651. print "</article>\n";
  652. }
  653. # output typedef in html5
  654. sub output_typedef_html5(%) {
  655. my %args = %{$_[0]};
  656. my ($parameter);
  657. my $count;
  658. my $html5id;
  659. $html5id = $args{'typedef'};
  660. $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
  661. print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
  662. print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
  663. print "<ol class=\"code\">\n";
  664. print "<li>";
  665. print "<span class=\"keyword\">typedef</span> ";
  666. print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
  667. print "</li>\n";
  668. print "</ol>\n";
  669. output_section_html5(@_);
  670. print "</article>\n";
  671. }
  672. # output struct in html5
  673. sub output_struct_html5(%) {
  674. my %args = %{$_[0]};
  675. my ($parameter);
  676. my $html5id;
  677. $html5id = $args{'struct'};
  678. $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
  679. print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
  680. print "<hgroup>\n";
  681. print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
  682. print "<h2>". $args{'purpose'} . "</h2>\n";
  683. print "</hgroup>\n";
  684. print "<ol class=\"code\">\n";
  685. print "<li>";
  686. print "<span class=\"type\">" . $args{'type'} . "</span> ";
  687. print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
  688. print "</li>\n";
  689. foreach $parameter (@{$args{'parameterlist'}}) {
  690. print "<li class=\"indent\">";
  691. if ($parameter =~ /^#/) {
  692. print "<span class=\"param\">" . $parameter ."</span>\n";
  693. print "</li>\n";
  694. next;
  695. }
  696. my $parameter_name = $parameter;
  697. $parameter_name =~ s/\[.*//;
  698. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  699. $type = $args{'parametertypes'}{$parameter};
  700. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  701. # pointer-to-function
  702. print "<span class=\"type\">$1</span> ";
  703. print "<span class=\"param\">$parameter</span>";
  704. print "<span class=\"type\">)</span> ";
  705. print "(<span class=\"args\">$2</span>);";
  706. } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  707. # bitfield
  708. print "<span class=\"type\">$1</span> ";
  709. print "<span class=\"param\">$parameter</span>";
  710. print "<span class=\"bits\">$2</span>;";
  711. } else {
  712. print "<span class=\"type\">$type</span> ";
  713. print "<span class=\"param\">$parameter</span>;";
  714. }
  715. print "</li>\n";
  716. }
  717. print "<li>};</li>\n";
  718. print "</ol>\n";
  719. print "<section>\n";
  720. print "<h1>Members</h1>\n";
  721. print "<dl>\n";
  722. foreach $parameter (@{$args{'parameterlist'}}) {
  723. ($parameter =~ /^#/) && next;
  724. my $parameter_name = $parameter;
  725. $parameter_name =~ s/\[.*//;
  726. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  727. print "<dt>" . $parameter . "</dt>\n";
  728. print "<dd>";
  729. output_highlight($args{'parameterdescs'}{$parameter_name});
  730. print "</dd>\n";
  731. }
  732. print "</dl>\n";
  733. print "</section>\n";
  734. output_section_html5(@_);
  735. print "</article>\n";
  736. }
  737. # output function in html5
  738. sub output_function_html5(%) {
  739. my %args = %{$_[0]};
  740. my ($parameter, $section);
  741. my $count;
  742. my $html5id;
  743. $html5id = $args{'function'};
  744. $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
  745. print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
  746. print "<hgroup>\n";
  747. print "<h1>" . $args{'function'} . "</h1>";
  748. print "<h2>" . $args{'purpose'} . "</h2>\n";
  749. print "</hgroup>\n";
  750. print "<ol class=\"code\">\n";
  751. print "<li>";
  752. print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
  753. print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
  754. print "</li>";
  755. $count = 0;
  756. foreach $parameter (@{$args{'parameterlist'}}) {
  757. print "<li class=\"indent\">";
  758. $type = $args{'parametertypes'}{$parameter};
  759. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  760. # pointer-to-function
  761. print "<span class=\"type\">$1</span> ";
  762. print "<span class=\"param\">$parameter</span>";
  763. print "<span class=\"type\">)</span> ";
  764. print "(<span class=\"args\">$2</span>)";
  765. } else {
  766. print "<span class=\"type\">$type</span> ";
  767. print "<span class=\"param\">$parameter</span>";
  768. }
  769. if ($count != $#{$args{'parameterlist'}}) {
  770. $count++;
  771. print ",";
  772. }
  773. print "</li>\n";
  774. }
  775. print "<li>)</li>\n";
  776. print "</ol>\n";
  777. print "<section>\n";
  778. print "<h1>Arguments</h1>\n";
  779. print "<p>\n";
  780. print "<dl>\n";
  781. foreach $parameter (@{$args{'parameterlist'}}) {
  782. my $parameter_name = $parameter;
  783. $parameter_name =~ s/\[.*//;
  784. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  785. print "<dt>" . $parameter . "</dt>\n";
  786. print "<dd>";
  787. output_highlight($args{'parameterdescs'}{$parameter_name});
  788. print "</dd>\n";
  789. }
  790. print "</dl>\n";
  791. print "</section>\n";
  792. output_section_html5(@_);
  793. print "</article>\n";
  794. }
  795. # output DOC: block header in html5
  796. sub output_blockhead_html5(%) {
  797. my %args = %{$_[0]};
  798. my ($parameter, $section);
  799. my $count;
  800. my $html5id;
  801. foreach $section (@{$args{'sectionlist'}}) {
  802. $html5id = $section;
  803. $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
  804. print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
  805. print "<h1>$section</h1>\n";
  806. print "<p>\n";
  807. output_highlight($args{'sections'}{$section});
  808. print "</p>\n";
  809. }
  810. print "</article>\n";
  811. }
  812. sub output_section_xml(%) {
  813. my %args = %{$_[0]};
  814. my $section;
  815. # print out each section
  816. $lineprefix=" ";
  817. foreach $section (@{$args{'sectionlist'}}) {
  818. print "<refsect1>\n";
  819. print "<title>$section</title>\n";
  820. if ($section =~ m/EXAMPLE/i) {
  821. print "<informalexample><programlisting>\n";
  822. $output_preformatted = 1;
  823. } else {
  824. print "<para>\n";
  825. }
  826. output_highlight($args{'sections'}{$section});
  827. $output_preformatted = 0;
  828. if ($section =~ m/EXAMPLE/i) {
  829. print "</programlisting></informalexample>\n";
  830. } else {
  831. print "</para>\n";
  832. }
  833. print "</refsect1>\n";
  834. }
  835. }
  836. # output function in XML DocBook
  837. sub output_function_xml(%) {
  838. my %args = %{$_[0]};
  839. my ($parameter, $section);
  840. my $count;
  841. my $id;
  842. $id = "API-" . $args{'function'};
  843. $id =~ s/[^A-Za-z0-9]/-/g;
  844. print "<refentry id=\"$id\">\n";
  845. print "<refentryinfo>\n";
  846. print " <title>LINUX</title>\n";
  847. print " <productname>Kernel Hackers Manual</productname>\n";
  848. print " <date>$man_date</date>\n";
  849. print "</refentryinfo>\n";
  850. print "<refmeta>\n";
  851. print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
  852. print " <manvolnum>9</manvolnum>\n";
  853. print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
  854. print "</refmeta>\n";
  855. print "<refnamediv>\n";
  856. print " <refname>" . $args{'function'} . "</refname>\n";
  857. print " <refpurpose>\n";
  858. print " ";
  859. output_highlight ($args{'purpose'});
  860. print " </refpurpose>\n";
  861. print "</refnamediv>\n";
  862. print "<refsynopsisdiv>\n";
  863. print " <title>Synopsis</title>\n";
  864. print " <funcsynopsis><funcprototype>\n";
  865. print " <funcdef>" . $args{'functiontype'} . " ";
  866. print "<function>" . $args{'function'} . " </function></funcdef>\n";
  867. $count = 0;
  868. if ($#{$args{'parameterlist'}} >= 0) {
  869. foreach $parameter (@{$args{'parameterlist'}}) {
  870. $type = $args{'parametertypes'}{$parameter};
  871. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  872. # pointer-to-function
  873. print " <paramdef>$1<parameter>$parameter</parameter>)\n";
  874. print " <funcparams>$2</funcparams></paramdef>\n";
  875. } else {
  876. print " <paramdef>" . $type;
  877. print " <parameter>$parameter</parameter></paramdef>\n";
  878. }
  879. }
  880. } else {
  881. print " <void/>\n";
  882. }
  883. print " </funcprototype></funcsynopsis>\n";
  884. print "</refsynopsisdiv>\n";
  885. # print parameters
  886. print "<refsect1>\n <title>Arguments</title>\n";
  887. if ($#{$args{'parameterlist'}} >= 0) {
  888. print " <variablelist>\n";
  889. foreach $parameter (@{$args{'parameterlist'}}) {
  890. my $parameter_name = $parameter;
  891. $parameter_name =~ s/\[.*//;
  892. print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
  893. print " <listitem>\n <para>\n";
  894. $lineprefix=" ";
  895. output_highlight($args{'parameterdescs'}{$parameter_name});
  896. print " </para>\n </listitem>\n </varlistentry>\n";
  897. }
  898. print " </variablelist>\n";
  899. } else {
  900. print " <para>\n None\n </para>\n";
  901. }
  902. print "</refsect1>\n";
  903. output_section_xml(@_);
  904. print "</refentry>\n\n";
  905. }
  906. # output struct in XML DocBook
  907. sub output_struct_xml(%) {
  908. my %args = %{$_[0]};
  909. my ($parameter, $section);
  910. my $id;
  911. $id = "API-struct-" . $args{'struct'};
  912. $id =~ s/[^A-Za-z0-9]/-/g;
  913. print "<refentry id=\"$id\">\n";
  914. print "<refentryinfo>\n";
  915. print " <title>LINUX</title>\n";
  916. print " <productname>Kernel Hackers Manual</productname>\n";
  917. print " <date>$man_date</date>\n";
  918. print "</refentryinfo>\n";
  919. print "<refmeta>\n";
  920. print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
  921. print " <manvolnum>9</manvolnum>\n";
  922. print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
  923. print "</refmeta>\n";
  924. print "<refnamediv>\n";
  925. print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
  926. print " <refpurpose>\n";
  927. print " ";
  928. output_highlight ($args{'purpose'});
  929. print " </refpurpose>\n";
  930. print "</refnamediv>\n";
  931. print "<refsynopsisdiv>\n";
  932. print " <title>Synopsis</title>\n";
  933. print " <programlisting>\n";
  934. print $args{'type'} . " " . $args{'struct'} . " {\n";
  935. foreach $parameter (@{$args{'parameterlist'}}) {
  936. if ($parameter =~ /^#/) {
  937. my $prm = $parameter;
  938. # convert data read & converted thru xml_escape() into &xyz; format:
  939. # This allows us to have #define macros interspersed in a struct.
  940. $prm =~ s/\\\\\\/\&/g;
  941. print "$prm\n";
  942. next;
  943. }
  944. my $parameter_name = $parameter;
  945. $parameter_name =~ s/\[.*//;
  946. defined($args{'parameterdescs'}{$parameter_name}) || next;
  947. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  948. $type = $args{'parametertypes'}{$parameter};
  949. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  950. # pointer-to-function
  951. print " $1 $parameter) ($2);\n";
  952. } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  953. # bitfield
  954. print " $1 $parameter$2;\n";
  955. } else {
  956. print " " . $type . " " . $parameter . ";\n";
  957. }
  958. }
  959. print "};";
  960. print " </programlisting>\n";
  961. print "</refsynopsisdiv>\n";
  962. print " <refsect1>\n";
  963. print " <title>Members</title>\n";
  964. if ($#{$args{'parameterlist'}} >= 0) {
  965. print " <variablelist>\n";
  966. foreach $parameter (@{$args{'parameterlist'}}) {
  967. ($parameter =~ /^#/) && next;
  968. my $parameter_name = $parameter;
  969. $parameter_name =~ s/\[.*//;
  970. defined($args{'parameterdescs'}{$parameter_name}) || next;
  971. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  972. print " <varlistentry>";
  973. print " <term>$parameter</term>\n";
  974. print " <listitem><para>\n";
  975. output_highlight($args{'parameterdescs'}{$parameter_name});
  976. print " </para></listitem>\n";
  977. print " </varlistentry>\n";
  978. }
  979. print " </variablelist>\n";
  980. } else {
  981. print " <para>\n None\n </para>\n";
  982. }
  983. print " </refsect1>\n";
  984. output_section_xml(@_);
  985. print "</refentry>\n\n";
  986. }
  987. # output enum in XML DocBook
  988. sub output_enum_xml(%) {
  989. my %args = %{$_[0]};
  990. my ($parameter, $section);
  991. my $count;
  992. my $id;
  993. $id = "API-enum-" . $args{'enum'};
  994. $id =~ s/[^A-Za-z0-9]/-/g;
  995. print "<refentry id=\"$id\">\n";
  996. print "<refentryinfo>\n";
  997. print " <title>LINUX</title>\n";
  998. print " <productname>Kernel Hackers Manual</productname>\n";
  999. print " <date>$man_date</date>\n";
  1000. print "</refentryinfo>\n";
  1001. print "<refmeta>\n";
  1002. print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
  1003. print " <manvolnum>9</manvolnum>\n";
  1004. print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
  1005. print "</refmeta>\n";
  1006. print "<refnamediv>\n";
  1007. print " <refname>enum " . $args{'enum'} . "</refname>\n";
  1008. print " <refpurpose>\n";
  1009. print " ";
  1010. output_highlight ($args{'purpose'});
  1011. print " </refpurpose>\n";
  1012. print "</refnamediv>\n";
  1013. print "<refsynopsisdiv>\n";
  1014. print " <title>Synopsis</title>\n";
  1015. print " <programlisting>\n";
  1016. print "enum " . $args{'enum'} . " {\n";
  1017. $count = 0;
  1018. foreach $parameter (@{$args{'parameterlist'}}) {
  1019. print " $parameter";
  1020. if ($count != $#{$args{'parameterlist'}}) {
  1021. $count++;
  1022. print ",";
  1023. }
  1024. print "\n";
  1025. }
  1026. print "};";
  1027. print " </programlisting>\n";
  1028. print "</refsynopsisdiv>\n";
  1029. print "<refsect1>\n";
  1030. print " <title>Constants</title>\n";
  1031. print " <variablelist>\n";
  1032. foreach $parameter (@{$args{'parameterlist'}}) {
  1033. my $parameter_name = $parameter;
  1034. $parameter_name =~ s/\[.*//;
  1035. print " <varlistentry>";
  1036. print " <term>$parameter</term>\n";
  1037. print " <listitem><para>\n";
  1038. output_highlight($args{'parameterdescs'}{$parameter_name});
  1039. print " </para></listitem>\n";
  1040. print " </varlistentry>\n";
  1041. }
  1042. print " </variablelist>\n";
  1043. print "</refsect1>\n";
  1044. output_section_xml(@_);
  1045. print "</refentry>\n\n";
  1046. }
  1047. # output typedef in XML DocBook
  1048. sub output_typedef_xml(%) {
  1049. my %args = %{$_[0]};
  1050. my ($parameter, $section);
  1051. my $id;
  1052. $id = "API-typedef-" . $args{'typedef'};
  1053. $id =~ s/[^A-Za-z0-9]/-/g;
  1054. print "<refentry id=\"$id\">\n";
  1055. print "<refentryinfo>\n";
  1056. print " <title>LINUX</title>\n";
  1057. print " <productname>Kernel Hackers Manual</productname>\n";
  1058. print " <date>$man_date</date>\n";
  1059. print "</refentryinfo>\n";
  1060. print "<refmeta>\n";
  1061. print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
  1062. print " <manvolnum>9</manvolnum>\n";
  1063. print "</refmeta>\n";
  1064. print "<refnamediv>\n";
  1065. print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
  1066. print " <refpurpose>\n";
  1067. print " ";
  1068. output_highlight ($args{'purpose'});
  1069. print " </refpurpose>\n";
  1070. print "</refnamediv>\n";
  1071. print "<refsynopsisdiv>\n";
  1072. print " <title>Synopsis</title>\n";
  1073. print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
  1074. print "</refsynopsisdiv>\n";
  1075. output_section_xml(@_);
  1076. print "</refentry>\n\n";
  1077. }
  1078. # output in XML DocBook
  1079. sub output_blockhead_xml(%) {
  1080. my %args = %{$_[0]};
  1081. my ($parameter, $section);
  1082. my $count;
  1083. my $id = $args{'module'};
  1084. $id =~ s/[^A-Za-z0-9]/-/g;
  1085. # print out each section
  1086. $lineprefix=" ";
  1087. foreach $section (@{$args{'sectionlist'}}) {
  1088. if (!$args{'content-only'}) {
  1089. print "<refsect1>\n <title>$section</title>\n";
  1090. }
  1091. if ($section =~ m/EXAMPLE/i) {
  1092. print "<example><para>\n";
  1093. $output_preformatted = 1;
  1094. } else {
  1095. print "<para>\n";
  1096. }
  1097. output_highlight($args{'sections'}{$section});
  1098. $output_preformatted = 0;
  1099. if ($section =~ m/EXAMPLE/i) {
  1100. print "</para></example>\n";
  1101. } else {
  1102. print "</para>";
  1103. }
  1104. if (!$args{'content-only'}) {
  1105. print "\n</refsect1>\n";
  1106. }
  1107. }
  1108. print "\n\n";
  1109. }
  1110. # output in XML DocBook
  1111. sub output_function_gnome {
  1112. my %args = %{$_[0]};
  1113. my ($parameter, $section);
  1114. my $count;
  1115. my $id;
  1116. $id = $args{'module'} . "-" . $args{'function'};
  1117. $id =~ s/[^A-Za-z0-9]/-/g;
  1118. print "<sect2>\n";
  1119. print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
  1120. print " <funcsynopsis>\n";
  1121. print " <funcdef>" . $args{'functiontype'} . " ";
  1122. print "<function>" . $args{'function'} . " ";
  1123. print "</function></funcdef>\n";
  1124. $count = 0;
  1125. if ($#{$args{'parameterlist'}} >= 0) {
  1126. foreach $parameter (@{$args{'parameterlist'}}) {
  1127. $type = $args{'parametertypes'}{$parameter};
  1128. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1129. # pointer-to-function
  1130. print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
  1131. print " <funcparams>$2</funcparams></paramdef>\n";
  1132. } else {
  1133. print " <paramdef>" . $type;
  1134. print " <parameter>$parameter</parameter></paramdef>\n";
  1135. }
  1136. }
  1137. } else {
  1138. print " <void>\n";
  1139. }
  1140. print " </funcsynopsis>\n";
  1141. if ($#{$args{'parameterlist'}} >= 0) {
  1142. print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
  1143. print "<tgroup cols=\"2\">\n";
  1144. print "<colspec colwidth=\"2*\">\n";
  1145. print "<colspec colwidth=\"8*\">\n";
  1146. print "<tbody>\n";
  1147. foreach $parameter (@{$args{'parameterlist'}}) {
  1148. my $parameter_name = $parameter;
  1149. $parameter_name =~ s/\[.*//;
  1150. print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
  1151. print " <entry>\n";
  1152. $lineprefix=" ";
  1153. output_highlight($args{'parameterdescs'}{$parameter_name});
  1154. print " </entry></row>\n";
  1155. }
  1156. print " </tbody></tgroup></informaltable>\n";
  1157. } else {
  1158. print " <para>\n None\n </para>\n";
  1159. }
  1160. # print out each section
  1161. $lineprefix=" ";
  1162. foreach $section (@{$args{'sectionlist'}}) {
  1163. print "<simplesect>\n <title>$section</title>\n";
  1164. if ($section =~ m/EXAMPLE/i) {
  1165. print "<example><programlisting>\n";
  1166. $output_preformatted = 1;
  1167. } else {
  1168. }
  1169. print "<para>\n";
  1170. output_highlight($args{'sections'}{$section});
  1171. $output_preformatted = 0;
  1172. print "</para>\n";
  1173. if ($section =~ m/EXAMPLE/i) {
  1174. print "</programlisting></example>\n";
  1175. } else {
  1176. }
  1177. print " </simplesect>\n";
  1178. }
  1179. print "</sect2>\n\n";
  1180. }
  1181. ##
  1182. # output function in man
  1183. sub output_function_man(%) {
  1184. my %args = %{$_[0]};
  1185. my ($parameter, $section);
  1186. my $count;
  1187. print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
  1188. print ".SH NAME\n";
  1189. print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
  1190. print ".SH SYNOPSIS\n";
  1191. if ($args{'functiontype'} ne "") {
  1192. print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
  1193. } else {
  1194. print ".B \"" . $args{'function'} . "\n";
  1195. }
  1196. $count = 0;
  1197. my $parenth = "(";
  1198. my $post = ",";
  1199. foreach my $parameter (@{$args{'parameterlist'}}) {
  1200. if ($count == $#{$args{'parameterlist'}}) {
  1201. $post = ");";
  1202. }
  1203. $type = $args{'parametertypes'}{$parameter};
  1204. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1205. # pointer-to-function
  1206. print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
  1207. } else {
  1208. $type =~ s/([^\*])$/$1 /;
  1209. print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
  1210. }
  1211. $count++;
  1212. $parenth = "";
  1213. }
  1214. print ".SH ARGUMENTS\n";
  1215. foreach $parameter (@{$args{'parameterlist'}}) {
  1216. my $parameter_name = $parameter;
  1217. $parameter_name =~ s/\[.*//;
  1218. print ".IP \"" . $parameter . "\" 12\n";
  1219. output_highlight($args{'parameterdescs'}{$parameter_name});
  1220. }
  1221. foreach $section (@{$args{'sectionlist'}}) {
  1222. print ".SH \"", uc $section, "\"\n";
  1223. output_highlight($args{'sections'}{$section});
  1224. }
  1225. }
  1226. ##
  1227. # output enum in man
  1228. sub output_enum_man(%) {
  1229. my %args = %{$_[0]};
  1230. my ($parameter, $section);
  1231. my $count;
  1232. print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
  1233. print ".SH NAME\n";
  1234. print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
  1235. print ".SH SYNOPSIS\n";
  1236. print "enum " . $args{'enum'} . " {\n";
  1237. $count = 0;
  1238. foreach my $parameter (@{$args{'parameterlist'}}) {
  1239. print ".br\n.BI \" $parameter\"\n";
  1240. if ($count == $#{$args{'parameterlist'}}) {
  1241. print "\n};\n";
  1242. last;
  1243. }
  1244. else {
  1245. print ", \n.br\n";
  1246. }
  1247. $count++;
  1248. }
  1249. print ".SH Constants\n";
  1250. foreach $parameter (@{$args{'parameterlist'}}) {
  1251. my $parameter_name = $parameter;
  1252. $parameter_name =~ s/\[.*//;
  1253. print ".IP \"" . $parameter . "\" 12\n";
  1254. output_highlight($args{'parameterdescs'}{$parameter_name});
  1255. }
  1256. foreach $section (@{$args{'sectionlist'}}) {
  1257. print ".SH \"$section\"\n";
  1258. output_highlight($args{'sections'}{$section});
  1259. }
  1260. }
  1261. ##
  1262. # output struct in man
  1263. sub output_struct_man(%) {
  1264. my %args = %{$_[0]};
  1265. my ($parameter, $section);
  1266. print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
  1267. print ".SH NAME\n";
  1268. print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
  1269. print ".SH SYNOPSIS\n";
  1270. print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
  1271. foreach my $parameter (@{$args{'parameterlist'}}) {
  1272. if ($parameter =~ /^#/) {
  1273. print ".BI \"$parameter\"\n.br\n";
  1274. next;
  1275. }
  1276. my $parameter_name = $parameter;
  1277. $parameter_name =~ s/\[.*//;
  1278. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  1279. $type = $args{'parametertypes'}{$parameter};
  1280. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1281. # pointer-to-function
  1282. print ".BI \" " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
  1283. } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  1284. # bitfield
  1285. print ".BI \" " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
  1286. } else {
  1287. $type =~ s/([^\*])$/$1 /;
  1288. print ".BI \" " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
  1289. }
  1290. print "\n.br\n";
  1291. }
  1292. print "};\n.br\n";
  1293. print ".SH Members\n";
  1294. foreach $parameter (@{$args{'parameterlist'}}) {
  1295. ($parameter =~ /^#/) && next;
  1296. my $parameter_name = $parameter;
  1297. $parameter_name =~ s/\[.*//;
  1298. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  1299. print ".IP \"" . $parameter . "\" 12\n";
  1300. output_highlight($args{'parameterdescs'}{$parameter_name});
  1301. }
  1302. foreach $section (@{$args{'sectionlist'}}) {
  1303. print ".SH \"$section\"\n";
  1304. output_highlight($args{'sections'}{$section});
  1305. }
  1306. }
  1307. ##
  1308. # output typedef in man
  1309. sub output_typedef_man(%) {
  1310. my %args = %{$_[0]};
  1311. my ($parameter, $section);
  1312. print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
  1313. print ".SH NAME\n";
  1314. print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
  1315. foreach $section (@{$args{'sectionlist'}}) {
  1316. print ".SH \"$section\"\n";
  1317. output_highlight($args{'sections'}{$section});
  1318. }
  1319. }
  1320. sub output_blockhead_man(%) {
  1321. my %args = %{$_[0]};
  1322. my ($parameter, $section);
  1323. my $count;
  1324. print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
  1325. foreach $section (@{$args{'sectionlist'}}) {
  1326. print ".SH \"$section\"\n";
  1327. output_highlight($args{'sections'}{$section});
  1328. }
  1329. }
  1330. ##
  1331. # output in text
  1332. sub output_function_text(%) {
  1333. my %args = %{$_[0]};
  1334. my ($parameter, $section);
  1335. my $start;
  1336. print "Name:\n\n";
  1337. print $args{'function'} . " - " . $args{'purpose'} . "\n";
  1338. print "\nSynopsis:\n\n";
  1339. if ($args{'functiontype'} ne "") {
  1340. $start = $args{'functiontype'} . " " . $args{'function'} . " (";
  1341. } else {
  1342. $start = $args{'function'} . " (";
  1343. }
  1344. print $start;
  1345. my $count = 0;
  1346. foreach my $parameter (@{$args{'parameterlist'}}) {
  1347. $type = $args{'parametertypes'}{$parameter};
  1348. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1349. # pointer-to-function
  1350. print $1 . $parameter . ") (" . $2;
  1351. } else {
  1352. print $type . " " . $parameter;
  1353. }
  1354. if ($count != $#{$args{'parameterlist'}}) {
  1355. $count++;
  1356. print ",\n";
  1357. print " " x length($start);
  1358. } else {
  1359. print ");\n\n";
  1360. }
  1361. }
  1362. print "Arguments:\n\n";
  1363. foreach $parameter (@{$args{'parameterlist'}}) {
  1364. my $parameter_name = $parameter;
  1365. $parameter_name =~ s/\[.*//;
  1366. print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
  1367. }
  1368. output_section_text(@_);
  1369. }
  1370. #output sections in text
  1371. sub output_section_text(%) {
  1372. my %args = %{$_[0]};
  1373. my $section;
  1374. print "\n";
  1375. foreach $section (@{$args{'sectionlist'}}) {
  1376. print "$section:\n\n";
  1377. output_highlight($args{'sections'}{$section});
  1378. }
  1379. print "\n\n";
  1380. }
  1381. # output enum in text
  1382. sub output_enum_text(%) {
  1383. my %args = %{$_[0]};
  1384. my ($parameter);
  1385. my $count;
  1386. print "Enum:\n\n";
  1387. print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
  1388. print "enum " . $args{'enum'} . " {\n";
  1389. $count = 0;
  1390. foreach $parameter (@{$args{'parameterlist'}}) {
  1391. print "\t$parameter";
  1392. if ($count != $#{$args{'parameterlist'}}) {
  1393. $count++;
  1394. print ",";
  1395. }
  1396. print "\n";
  1397. }
  1398. print "};\n\n";
  1399. print "Constants:\n\n";
  1400. foreach $parameter (@{$args{'parameterlist'}}) {
  1401. print "$parameter\n\t";
  1402. print $args{'parameterdescs'}{$parameter} . "\n";
  1403. }
  1404. output_section_text(@_);
  1405. }
  1406. # output typedef in text
  1407. sub output_typedef_text(%) {
  1408. my %args = %{$_[0]};
  1409. my ($parameter);
  1410. my $count;
  1411. print "Typedef:\n\n";
  1412. print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
  1413. output_section_text(@_);
  1414. }
  1415. # output struct as text
  1416. sub output_struct_text(%) {
  1417. my %args = %{$_[0]};
  1418. my ($parameter);
  1419. print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
  1420. print $args{'type'} . " " . $args{'struct'} . " {\n";
  1421. foreach $parameter (@{$args{'parameterlist'}}) {
  1422. if ($parameter =~ /^#/) {
  1423. print "$parameter\n";
  1424. next;
  1425. }
  1426. my $parameter_name = $parameter;
  1427. $parameter_name =~ s/\[.*//;
  1428. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  1429. $type = $args{'parametertypes'}{$parameter};
  1430. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1431. # pointer-to-function
  1432. print "\t$1 $parameter) ($2);\n";
  1433. } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  1434. # bitfield
  1435. print "\t$1 $parameter$2;\n";
  1436. } else {
  1437. print "\t" . $type . " " . $parameter . ";\n";
  1438. }
  1439. }
  1440. print "};\n\n";
  1441. print "Members:\n\n";
  1442. foreach $parameter (@{$args{'parameterlist'}}) {
  1443. ($parameter =~ /^#/) && next;
  1444. my $parameter_name = $parameter;
  1445. $parameter_name =~ s/\[.*//;
  1446. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  1447. print "$parameter\n\t";
  1448. print $args{'parameterdescs'}{$parameter_name} . "\n";
  1449. }
  1450. print "\n";
  1451. output_section_text(@_);
  1452. }
  1453. sub output_blockhead_text(%) {
  1454. my %args = %{$_[0]};
  1455. my ($parameter, $section);
  1456. foreach $section (@{$args{'sectionlist'}}) {
  1457. print " $section:\n";
  1458. print " -> ";
  1459. output_highlight($args{'sections'}{$section});
  1460. }
  1461. }
  1462. ## list mode output functions
  1463. sub output_function_list(%) {
  1464. my %args = %{$_[0]};
  1465. print $args{'function'} . "\n";
  1466. }
  1467. # output enum in list
  1468. sub output_enum_list(%) {
  1469. my %args = %{$_[0]};
  1470. print $args{'enum'} . "\n";
  1471. }
  1472. # output typedef in list
  1473. sub output_typedef_list(%) {
  1474. my %args = %{$_[0]};
  1475. print $args{'typedef'} . "\n";
  1476. }
  1477. # output struct as list
  1478. sub output_struct_list(%) {
  1479. my %args = %{$_[0]};
  1480. print $args{'struct'} . "\n";
  1481. }
  1482. sub output_blockhead_list(%) {
  1483. my %args = %{$_[0]};
  1484. my ($parameter, $section);
  1485. foreach $section (@{$args{'sectionlist'}}) {
  1486. print "DOC: $section\n";
  1487. }
  1488. }
  1489. ##
  1490. # generic output function for all types (function, struct/union, typedef, enum);
  1491. # calls the generated, variable output_ function name based on
  1492. # functype and output_mode
  1493. sub output_declaration {
  1494. no strict 'refs';
  1495. my $name = shift;
  1496. my $functype = shift;
  1497. my $func = "output_${functype}_$output_mode";
  1498. if (($function_only==0) ||
  1499. ( $function_only == 1 && defined($function_table{$name})) ||
  1500. ( $function_only == 2 && !defined($function_table{$name})))
  1501. {
  1502. &$func(@_);
  1503. $section_counter++;
  1504. }
  1505. }
  1506. ##
  1507. # generic output function - calls the right one based on current output mode.
  1508. sub output_blockhead {
  1509. no strict 'refs';
  1510. my $func = "output_blockhead_" . $output_mode;
  1511. &$func(@_);
  1512. $section_counter++;
  1513. }
  1514. ##
  1515. # takes a declaration (struct, union, enum, typedef) and
  1516. # invokes the right handler. NOT called for functions.
  1517. sub dump_declaration($$) {
  1518. no strict 'refs';
  1519. my ($prototype, $file) = @_;
  1520. my $func = "dump_" . $decl_type;
  1521. &$func(@_);
  1522. }
  1523. sub dump_union($$) {
  1524. dump_struct(@_);
  1525. }
  1526. sub dump_struct($$) {
  1527. my $x = shift;
  1528. my $file = shift;
  1529. my $nested;
  1530. if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
  1531. #my $decl_type = $1;
  1532. $declaration_name = $2;
  1533. my $members = $3;
  1534. # ignore embedded structs or unions
  1535. $members =~ s/({.*})//g;
  1536. $nested = $1;
  1537. # ignore members marked private:
  1538. $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
  1539. $members =~ s/\/\*\s*private:.*//gos;
  1540. # strip comments:
  1541. $members =~ s/\/\*.*?\*\///gos;
  1542. $nested =~ s/\/\*.*?\*\///gos;
  1543. # strip kmemcheck_bitfield_{begin,end}.*;
  1544. $members =~ s/kmemcheck_bitfield_.*?;//gos;
  1545. # strip attributes
  1546. $members =~ s/__aligned\s*\(.+\)//gos;
  1547. create_parameterlist($members, ';', $file);
  1548. check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
  1549. output_declaration($declaration_name,
  1550. 'struct',
  1551. {'struct' => $declaration_name,
  1552. 'module' => $modulename,
  1553. 'parameterlist' => \@parameterlist,
  1554. 'parameterdescs' => \%parameterdescs,
  1555. 'parametertypes' => \%parametertypes,
  1556. 'sectionlist' => \@sectionlist,
  1557. 'sections' => \%sections,
  1558. 'purpose' => $declaration_purpose,
  1559. 'type' => $decl_type
  1560. });
  1561. }
  1562. else {
  1563. print STDERR "Error(${file}:$.): Cannot parse struct or…

Large files files are truncated, but you can click here to view the full file