开通博客赚积分
发布资源赚积分
分类

源码开发语言/平台
当前位置：首页 > 源码/资料 > 嵌入式/单片机编程 > 嵌入式Linux > 查看源码
kernel-doc
资源名称：SBC-2410X_kernel.tar.gz　[点击查看]
上传用户：lgb322
上传日期：2013-02-24
资源大小：30529k
文件大小：44k
源码类别：

嵌入式Linux

开发平台：

Unix_Linux

kernel-doc：源码内容
  1. #!/usr/bin/perl -w
  3. use strict;
  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. ##   ##
  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             ##
  15. # w.o. 03-11-2000: added the '-filelist' option.
  17. # 18/01/2001 -  Cleanups
  18. #  Functions prototyped as foo(void) same as foo()
  19. #  Stop eval'ing where we don't need to.
  20. # -- huggie@earth.li
  22. # 27/06/2001 -  Allowed whitespace after initial "/**" and
  23. #               allowed comments before function declarations.
  24. # -- Christian Kreibich <ck@whoop.org>
  26. # Still to do:
  27. #  - add perldoc documentation
  28. #  - Look more closely at some of the scarier bits :)
  30. # 26/05/2001 -  Support for separate source and object trees.
  31. # Return error code.
  32. #  Keith Owens <kaos@ocs.com.au>
  34. # 23/09/2001 - Added support for typedefs, structs, enums and unions
  35. #              Support for Context section; can be terminated using empty line
  36. #              Small fixes (like spaces vs. s in regex)
  37. # -- Tim Jansen <tim@tjansen.de>
  40. #
  41. # This will read a 'c' file and scan for embedded comments in the
  42. # style of gnome comments (+minor extensions - see below).
  43. #
  45. # Note: This only supports 'c'.
  47. # usage:
  48. # kerneldoc [ -docbook | -html | -text | -man ]
  49. #           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
  50. # or
  51. #           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
  52. #
  53. #  Set output format using one of -docbook -html -text or -man.  Default is man.
  54. #
  55. #  -function funcname
  56. # If set, then only generate documentation for the given function(s).  All
  57. # other functions are ignored.
  58. #
  59. #  -nofunction funcname
  60. # If set, then only generate documentation for the other function(s).  All
  61. # other functions are ignored. Cannot be used with -function together
  62. # (yes thats a bug - perl hackers can fix it 8))
  63. #
  64. #  c files - list of 'c' files to process
  65. #
  66. #  All output goes to stdout, with errors to stderr.
  68. #
  69. # format of comments.
  70. # In the following table, (...)? signifies optional structure.
  71. #                         (...)* signifies 0 or more structure elements
  72. # /**
  73. #  * function_name(:)? (- short description)?
  74. # (* @parameterx: (description of parameter x)?)*
  75. # (* a blank line)?
  76. #  * (Description:)? (Description of function)?
  77. #  * (section header: (section description)? )*
  78. #  (*)?*/
  79. #
  80. # So .. the trivial example would be:
  81. #
  82. # /**
  83. #  * my_function
  84. #  **/
  85. #
  86. # If the Description: header tag is ommitted, then there must be a blank line
  87. # after the last parameter specification.
  88. # e.g.
  89. # /**
  90. #  * my_function - does my stuff
  91. #  * @my_arg: its mine damnit
  92. #  *
  93. #  * Does my stuff explained. 
  94. #  */
  95. #
  96. #  or, could also use:
  97. # /**
  98. #  * my_function - does my stuff
  99. #  * @my_arg: its mine damnit
  100. #  * Description: Does my stuff explained. 
  101. #  */
  102. # etc.
  103. #
  104. # Beside functions you can also write documentation for structs, unions, 
  105. # enums and typedefs. Instead of the function name you must write the name 
  106. # of the declaration;  the struct/union/enum/typedef must always precede 
  107. # the name. Nesting of declarations is not supported. 
  108. # Use the argument mechanism to document members or constants. In 
  109. # structs and unions you must declare one member per declaration 
  110. # (comma-separated members are not allowed -  the parser does not support 
  111. # this).
  112. # e.g.
  113. # /**
  114. #  * struct my_struct - short description
  115. #  * @a: first member
  116. #  * @b: second member
  117. #  * 
  118. #  * Longer description
  119. #  */
  120. # struct my_struct {
  121. #     int a;
  122. #     int b;
  123. # };
  124. #
  125. # All descriptions can be multiline, except the short function description.
  126. # 
  127. # You can also add additional sections. When documenting kernel functions you 
  128. # should document the "Context:" of the function, e.g. whether the functions 
  129. # can be called form interrupts. Unlike other sections you can end it with an
  130. # empty line. 
  131. # Example-sections should contain the string EXAMPLE so that they are marked 
  132. # appropriately in DocBook.
  133. #
  134. # Example:
  135. # /**
  136. #  * user_function - function that can only be called in user context
  137. #  * @a: some argument
  138. #  * Context: !in_interrupt()
  139. #  * 
  140. #  * Some description
  141. #  * Example:
  142. #  *    user_function(22);
  143. #  */
  144. # ...
  145. #
  146. #
  147. # All descriptive text is further processed, scanning for the following special
  148. # patterns, which are highlighted appropriately.
  149. #
  150. # 'funcname()' - function
  151. # '$ENVVAR' - environmental variable
  152. # '&struct_name' - name of a structure (up to two words including 'struct')
  153. # '@parameter' - name of a parameter
  154. # '%CONST' - name of a constant.
  156. my $errors = 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 = '&((structs*)?[_w]+)';
  163. my $type_env = '($w+)';
  165. # Output conversion substitutions.
  166. #  One for each output format
  168. # these work fairly well
  169. my %highlights_html = ( $type_constant, "<i>$1</i>",
  170. $type_func, "<b>$1</b>",
  171. $type_struct, "<i>$1</i>",
  172. $type_param, "<tt><b>$1</b></tt>" );
  173. my $blankline_html = "<p>";
  175. # sgml, docbook format
  176. my %highlights_sgml = ( "([^=])\"([^\"<]+)\"", "$1<quote>$2</quote>",
  177. $type_constant, "<constant>$1</constant>",
  178. $type_func, "<function>$1</function>",
  179. $type_struct, "<structname>$1</structname>",
  180. $type_env, "<envar>$1</envar>",
  181. $type_param, "<parameter>$1</parameter>" );
  182. my $blankline_sgml = "</para><para>n";
  184. # gnome, docbook format
  185. my %highlights_gnome = ( $type_constant, "<replaceable class="option">$1</replaceable>",
  186.  $type_func, "<function>$1</function>",
  187.  $type_struct, "<structname>$1</structname>",
  188.  $type_env, "<envar>$1</envar>",
  189.  $type_param, "<parameter>$1</parameter>" );
  190. my $blankline_gnome = "</para><para>n";
  192. # these are pretty rough
  193. my %highlights_man = ( $type_constant, "$1",
  194.        $type_func, "\\fB$1\\fP",
  195.        $type_struct, "\\fI$1\\fP",
  196.        $type_param, "\\fI$1\\fP" );
  197. my $blankline_man = "";
  199. # text-mode
  200. my %highlights_text = ( $type_constant, "$1",
  201. $type_func, "$1",
  202. $type_struct, "$1",
  203. $type_param, "$1" );
  204. my $blankline_text = "";
  207. sub usage {
  208.     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]n";
  209.     print "         [ -function funcname [ -function funcname ...] ]n";
  210.     print "         [ -nofunction funcname [ -nofunction funcname ...] ]n";
  211.     print "         c source file(s) > outputfilen";
  212.     exit 1;
  213. }
  215. # read arguments
  216. if ($#ARGV==-1) {
  217.     usage();
  218. }
  220. my $verbose = 0;
  221. my $output_mode = "man";
  222. my %highlights = %highlights_man;
  223. my $blankline = $blankline_man;
  224. my $modulename = "Kernel API";
  225. my $function_only = 0;
  226. my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 
  227. 'July', 'August', 'September', 'October', 
  228. 'November', 'December')[(localtime)[4]] . 
  229.   " " . ((localtime)[5]+1900);
  231. # Essentially these are globals
  232. # They probably want to be tidied up made more localised or summat.
  233. # CAVEAT EMPTOR!  Some of the others I localised may not want to be which
  234. # could cause "use of undefined value" or other bugs.
  235. my ($function, %function_table,%parametertypes,$declaration_purpose);
  236. my ($type,$file,$declaration_name,$return_type);
  237. my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
  239. my $lineprefix="";
  241. # states
  242. # 0 - normal code
  243. # 1 - looking for function name
  244. # 2 - scanning field start.
  245. # 3 - scanning prototype.
  246. # 4 - documentation block
  247. my $state;
  249. #declaration types: can be
  250. # 'function', 'struct', 'union', 'enum', 'typedef'
  251. my $decl_type;
  253. my $doc_special = "@%$&";
  255. my $doc_start = '^/**s*$'; # Allow whitespace at end of comment start.
  256. my $doc_end = '*/';
  257. my $doc_com = 's**s*';
  258. my $doc_decl = $doc_com.'(w+)';
  259. my $doc_sect = $doc_com.'(['.$doc_special.']?[w ]+):(.*)';
  260. my $doc_content = $doc_com.'(.*)';
  261. my $doc_block = $doc_com.'DOC:s*(.*)?';
  263. my %constants;
  264. my %parameterdescs;
  265. my @parameterlist;
  266. my %sections;
  267. my @sectionlist;
  269. my $contents = "";
  270. my $section_default = "Description"; # default section
  271. my $section_intro = "Introduction";
  272. my $section = $section_default;
  273. my $section_context = "Context";
  275. my $undescribed = "-- undescribed --";
  277. reset_state();
  279. while ($ARGV[0] =~ m/^-(.*)/) {
  280.     my $cmd = shift @ARGV;
  281.     if ($cmd eq "-html") {
  282. $output_mode = "html";
  283. %highlights = %highlights_html;
  284. $blankline = $blankline_html;
  285.     } elsif ($cmd eq "-man") {
  286. $output_mode = "man";
  287. %highlights = %highlights_man;
  288. $blankline = $blankline_man;
  289.     } elsif ($cmd eq "-text") {
  290. $output_mode = "text";
  291. %highlights = %highlights_text;
  292. $blankline = $blankline_text;
  293.     } elsif ($cmd eq "-docbook") {
  294. $output_mode = "sgml";
  295. %highlights = %highlights_sgml;
  296. $blankline = $blankline_sgml;
  297.     } elsif ($cmd eq "-gnome") {
  298. $output_mode = "gnome";
  299. %highlights = %highlights_gnome;
  300. $blankline = $blankline_gnome;
  301.     } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
  302. $modulename = shift @ARGV;
  303.     } elsif ($cmd eq "-function") { # to only output specific functions
  304. $function_only = 1;
  305. $function = shift @ARGV;
  306. $function_table{$function} = 1;
  307.     } elsif ($cmd eq "-nofunction") { # to only output specific functions
  308. $function_only = 2;
  309. $function = shift @ARGV;
  310. $function_table{$function} = 1;
  311.     } elsif ($cmd eq "-v") {
  312. $verbose = 1;
  313.     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
  314. usage();
  315.     } elsif ($cmd eq '-filelist') {
  316.     $filelist = shift @ARGV;
  317.     }
  318. }
  321. # generate a sequence of code that will splice in highlighting information
  322. # using the s// operator.
  323. my $dohighlight = "";
  324. foreach my $pattern (keys %highlights) {
  325. #    print "scanning pattern $pattern ($highlights{$pattern})n";
  326.     $dohighlight .=  "$contents =~ s:$pattern:$highlights{$pattern}:gs;n";
  327. }
  329. ##
  330. # dumps section contents to arrays/hashes intended for that purpose.
  331. #
  332. sub dump_section {
  333.     my $name = shift;
  334.     my $contents = join "n", @_;
  336.     if ($name =~ m/$type_constant/) {
  337. $name = $1;
  338. # print STDERR "constant section '$1' = '$contents'n";
  339. $constants{$name} = $contents;
  340.     } elsif ($name =~ m/$type_param/) {
  341. # print STDERR "parameter def '$1' = '$contents'n";
  342. $name = $1;
  343. $parameterdescs{$name} = $contents;
  344.     } else {
  345. # print STDERR "other section '$name' = '$contents'n";
  346. $sections{$name} = $contents;
  347. push @sectionlist, $name;
  348.     }
  349. }
  351. ##
  352. # output function
  353. #
  354. # parameterdescs, a hash.
  355. #  function => "function name"
  356. #  parameterlist => @list of parameters
  357. #  parameterdescs => %parameter descriptions
  358. #  sectionlist => @list of sections
  359. #  sections => %descriont descriptions
  360. #  
  362. sub output_highlight {
  363.     my $contents = join "n",@_;
  364.     my $line;
  366. #   DEBUG
  367. #   if (!defined $contents) {
  368. # use Carp;
  369. # confess "output_highlight got called with no args?n";
  370. #   }
  372.     eval $dohighlight;
  373.     die $@ if $@;
  374.     foreach $line (split "n", $contents) {
  375.       if ($line eq ""){
  376.     print $lineprefix, $blankline;
  377. } else {
  378.             $line =~ s/\\\/&/g;
  379.     print $lineprefix, $line;
  380. }
  381. print "n";
  382.     }
  383. }
  385. #output sections in html
  386. sub output_section_html(%) {
  387.     my %args = %{$_[0]};
  388.     my $section;
  390.     foreach $section (@{$args{'sectionlist'}}) {
  391. print "<h3>$section</h3>n";
  392. print "<blockquote>n";
  393. output_highlight($args{'sections'}{$section});
  394. print "</blockquote>n";
  395.     }  
  396. }
  398. # output enum in html
  399. sub output_enum_html(%) {
  400.     my %args = %{$_[0]};
  401.     my ($parameter);
  402.     my $count;
  403.     print "<h2>enum ".$args{'enum'}."</h2>n";
  405.     print "<b>enum ".$args{'enum'}."</b> {<br>n";
  406.     $count = 0;
  407.     foreach $parameter (@{$args{'parameterlist'}}) {
  408.         print " <b>".$parameter."</b>";
  409. if ($count != $#{$args{'parameterlist'}}) {
  410.     $count++;
  411.     print ",n";
  412. }
  413. print "<br>";
  414.     }
  415.     print "};<br>n";
  417.     print "<h3>Constants</h3>n";
  418.     print "<dl>n";
  419.     foreach $parameter (@{$args{'parameterlist'}}) {
  420. print "<dt><b>".$parameter."</b>n";
  421. print "<dd>";
  422. output_highlight($args{'parameterdescs'}{$parameter});
  423.     }
  424.     print "</dl>n";
  425.     output_section_html(@_);
  426.     print "<hr>n";
  427. }
  429. # output tyepdef in html
  430. sub output_typedef_html(%) {
  431.     my %args = %{$_[0]};
  432.     my ($parameter);
  433.     my $count;
  434.     print "<h2>typedef ".$args{'typedef'}."</h2>n";
  436.     print "<b>typedef ".$args{'typedef'}."</b>n";
  437.     output_section_html(@_);
  438.     print "<hr>n";
  439. }
  441. # output struct in html
  442. sub output_struct_html(%) {
  443.     my %args = %{$_[0]};
  444.     my ($parameter);
  446.     print "<h2>".$args{'type'}." ".$args{'struct'}."</h2>n";
  447.     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>n";
  448.     foreach $parameter (@{$args{'parameterlist'}}) {
  449.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  450. $type = $args{'parametertypes'}{$parameter};
  451. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  452.     # pointer-to-function
  453.     print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>n";
  454. } elsif ($type =~ m/^(.*?)s*(:.*)/) {
  455.     print " <i>$1</i> <b>$parameter</b>$2;<br>n";
  456. } else {
  457.     print " <i>$type</i> <b>$parameter</b>;<br>n";
  458. }
  459.     }
  460.     print "};<br>n";
  462.     print "<h3>Members</h3>n";
  463.     print "<dl>n";
  464.     foreach $parameter (@{$args{'parameterlist'}}) {
  465.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  466. print "<dt><b>".$parameter."</b>n";
  467. print "<dd>";
  468. output_highlight($args{'parameterdescs'}{$parameter});
  469.     }
  470.     print "</dl>n";
  471.     output_section_html(@_);
  472.     print "<hr>n";
  473. }
  475. # output function in html
  476. sub output_function_html(%) {
  477.     my %args = %{$_[0]};
  478.     my ($parameter, $section);
  479.     my $count;
  480.     print "<h2>Function</h2>n";
  482.     print "<i>".$args{'functiontype'}."</i>n";
  483.     print "<b>".$args{'function'}."</b>n";
  484.     print "(";
  485.     $count = 0;
  486.     foreach $parameter (@{$args{'parameterlist'}}) {
  487. $type = $args{'parametertypes'}{$parameter};
  488. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  489.     # pointer-to-function
  490.     print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
  491. } else {
  492.     print "<i>".$type."</i> <b>".$parameter."</b>";
  493. }
  494. if ($count != $#{$args{'parameterlist'}}) {
  495.     $count++;
  496.     print ",n";
  497. }
  498.     }
  499.     print ")n";
  501.     print "<h3>Arguments</h3>n";
  502.     print "<dl>n";
  503.     foreach $parameter (@{$args{'parameterlist'}}) {
  504.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  505. print "<dt><b>".$parameter."</b>n";
  506. print "<dd>";
  507. output_highlight($args{'parameterdescs'}{$parameter});
  508.     }
  509.     print "</dl>n";
  510.     output_section_html(@_);
  511.     print "<hr>n";
  512. }
  514. # output intro in html
  515. sub output_intro_html(%) {
  516.     my %args = %{$_[0]};
  517.     my ($parameter, $section);
  518.     my $count;
  520.     foreach $section (@{$args{'sectionlist'}}) {
  521. print "<h3>$section</h3>n";
  522. print "<ul>n";
  523. output_highlight($args{'sections'}{$section});
  524. print "</ul>n";
  525.     }
  526.     print "<hr>n";
  527. }
  529. sub output_section_sgml(%) {
  530.     my %args = %{$_[0]};
  531.     my $section;    
  532.     # print out each section
  533.     $lineprefix="   ";
  534.     foreach $section (@{$args{'sectionlist'}}) {
  535. print "<refsect1>n <title>$section</title>n <para>n";
  536. if ($section =~ m/EXAMPLE/i) {
  537.     print "<example><para>n";
  538. }
  539. output_highlight($args{'sections'}{$section});
  540. if ($section =~ m/EXAMPLE/i) {
  541.     print "</para></example>n";
  542. }
  543. print " </para>n</refsect1>n";
  544.     }
  545. }
  547. # output function in sgml DocBook
  548. sub output_function_sgml(%) {
  549.     my %args = %{$_[0]};
  550.     my ($parameter, $section);
  551.     my $count;
  552.     my $id;
  554.     $id = "API-".$args{'function'};
  555.     $id =~ s/[^A-Za-z0-9]/-/g;
  557.     print "<refentry>n";
  558.     print "<refmeta>n";
  559.     print "<refentrytitle><phrase id="$id">".$args{'function'}."</phrase></refentrytitle>n";
  560.     print "</refmeta>n";
  561.     print "<refnamediv>n";
  562.     print " <refname>".$args{'function'}."</refname>n";
  563.     print " <refpurpose>n";
  564.     print "  ";
  565.     output_highlight ($args{'purpose'});
  566.     print " </refpurpose>n";
  567.     print "</refnamediv>n";
  569.     print "<refsynopsisdiv>n";
  570.     print " <title>Synopsis</title>n";
  571.     print "  <funcsynopsis><funcprototype>n";
  572.     print "   <funcdef>".$args{'functiontype'}." ";
  573.     print "<function>".$args{'function'}." </function></funcdef>n";
  575.     $count = 0;
  576.     if ($#{$args{'parameterlist'}} >= 0) {
  577. foreach $parameter (@{$args{'parameterlist'}}) {
  578.     $type = $args{'parametertypes'}{$parameter};
  579.     if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  580. # pointer-to-function
  581. print "   <paramdef>$1<parameter>$parameter</parameter>)n";
  582. print "     <funcparams>$2</funcparams></paramdef>n";
  583.     } else {
  584. print "   <paramdef>".$type;
  585. print " <parameter>$parameter</parameter></paramdef>n";
  586.     }
  587. }
  588.     } else {
  589. print "  <void>n";
  590.     }
  591.     print "  </funcprototype></funcsynopsis>n";
  592.     print "</refsynopsisdiv>n";
  594.     # print parameters
  595.     print "<refsect1>n <title>Arguments</title>n";
  596.     if ($#{$args{'parameterlist'}} >= 0) {
  597. print " <variablelist>n";
  598. foreach $parameter (@{$args{'parameterlist'}}) {
  599.     print "  <varlistentry>n   <term><parameter>$parameter</parameter></term>n";
  600.     print "   <listitem>n    <para>n";
  601.     $lineprefix="     ";
  602.     output_highlight($args{'parameterdescs'}{$parameter});
  603.     print "    </para>n   </listitem>n  </varlistentry>n";
  604. }
  605. print " </variablelist>n";
  606.     } else {
  607. print " <para>n  Nonen </para>n";
  608.     }
  609.     print "</refsect1>n";
  611.     output_section_sgml(@_);
  612.     print "</refentry>nn";
  613. }
  615. # output struct in sgml DocBook
  616. sub output_struct_sgml(%) {
  617.     my %args = %{$_[0]};
  618.     my ($parameter, $section);
  619.     my $id;
  621.     $id = "API-struct-".$args{'struct'};
  622.     $id =~ s/[^A-Za-z0-9]/-/g;
  624.     print "<refentry>n";
  625.     print "<refmeta>n";
  626.     print "<refentrytitle><phrase id="$id">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>n";
  627.     print "</refmeta>n";
  628.     print "<refnamediv>n";
  629.     print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>n";
  630.     print " <refpurpose>n";
  631.     print "  ";
  632.     output_highlight ($args{'purpose'});
  633.     print " </refpurpose>n";
  634.     print "</refnamediv>n";
  636.     print "<refsynopsisdiv>n";
  637.     print " <title>Synopsis</title>n";
  638.     print "  <programlisting>n";
  639.     print $args{'type'}." ".$args{'struct'}." {n";
  640.     foreach $parameter (@{$args{'parameterlist'}}) {
  641.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  642. $type = $args{'parametertypes'}{$parameter};
  643. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  644.     # pointer-to-function
  645.     print "  $1 $parameter ($2);n";
  646. } elsif ($type =~ m/^(.*?)s*(:.*)/) {
  647.     print "  $1 $parameter$2;n";
  648. } else {
  649.     print "  ".$type." ".$parameter.";n";
  650. }
  651.     }
  652.     print "};";
  653.     print "  </programlisting>n";
  654.     print "</refsynopsisdiv>n";
  656.     print " <refsect1>n";
  657.     print "  <title>Members</title>n";
  659.     print "  <variablelist>n";
  660.     foreach $parameter (@{$args{'parameterlist'}}) {
  661.       ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  662.       print "    <varlistentry>";
  663.       print "      <term>$parameter</term>n";
  664.       print "      <listitem><para>n";
  665.       output_highlight($args{'parameterdescs'}{$parameter});
  666.       print "      </para></listitem>n";
  667.       print "    </varlistentry>n";
  668.     }
  669.     print "  </variablelist>n";
  670.     print " </refsect1>n";
  672.     output_section_sgml(@_);
  674.     print "</refentry>nn";
  675. }
  677. # output enum in sgml DocBook
  678. sub output_enum_sgml(%) {
  679.     my %args = %{$_[0]};
  680.     my ($parameter, $section);
  681.     my $count;
  682.     my $id;
  684.     $id = "API-enum-".$args{'enum'};
  685.     $id =~ s/[^A-Za-z0-9]/-/g;
  687.     print "<refentry>n";
  688.     print "<refmeta>n";
  689.     print "<refentrytitle><phrase id="$id">enum ".$args{'enum'}."</phrase></refentrytitle>n";
  690.     print "</refmeta>n";
  691.     print "<refnamediv>n";
  692.     print " <refname>enum ".$args{'enum'}."</refname>n";
  693.     print " <refpurpose>n";
  694.     print "  ";
  695.     output_highlight ($args{'purpose'});
  696.     print " </refpurpose>n";
  697.     print "</refnamediv>n";
  699.     print "<refsynopsisdiv>n";
  700.     print " <title>Synopsis</title>n";
  701.     print "  <programlisting>n";
  702.     print "enum ".$args{'enum'}." {n";
  703.     $count = 0;
  704.     foreach $parameter (@{$args{'parameterlist'}}) {
  705.         print "  $parameter";
  706.         if ($count != $#{$args{'parameterlist'}}) {
  707.     $count++;
  708.     print ",";
  709.         }
  710. print "n";
  711.     }
  712.     print "};";
  713.     print "  </programlisting>n";
  714.     print "</refsynopsisdiv>n";
  716.     print "<refsect1>n";
  717.     print " <title>Constants</title>n";    
  718.     print "  <variablelist>n";
  719.     foreach $parameter (@{$args{'parameterlist'}}) {
  720.       print "    <varlistentry>";
  721.       print "      <term>$parameter</term>n";
  722.       print "      <listitem><para>n";
  723.       output_highlight($args{'parameterdescs'}{$parameter});
  724.       print "      </para></listitem>n";
  725.       print "    </varlistentry>n";
  726.     }
  727.     print "  </variablelist>n";
  728.     print "</refsect1>n";
  730.     output_section_sgml(@_);
  732.     print "</refentry>nn";
  733. }
  735. # output typedef in sgml DocBook
  736. sub output_typedef_sgml(%) {
  737.     my %args = %{$_[0]};
  738.     my ($parameter, $section);
  739.     my $id;
  741.     $id = "API-typedef-".$args{'typedef'};
  742.     $id =~ s/[^A-Za-z0-9]/-/g;
  744.     print "<refentry>n";
  745.     print "<refmeta>n";
  746.     print "<refentrytitle><phrase id="$id">typedef ".$args{'typedef'}."</phrase></refentrytitle>n";
  747.     print "</refmeta>n";
  748.     print "<refnamediv>n";
  749.     print " <refname>typedef ".$args{'typedef'}."</refname>n";
  750.     print " <refpurpose>n";
  751.     print "  ";
  752.     output_highlight ($args{'purpose'});
  753.     print " </refpurpose>n";
  754.     print "</refnamediv>n";
  756.     print "<refsynopsisdiv>n";
  757.     print " <title>Synopsis</title>n";
  758.     print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>n";
  759.     print "</refsynopsisdiv>n";
  761.     output_section_sgml(@_);
  763.     print "</refentry>nn";
  764. }
  766. # output in sgml DocBook
  767. sub output_intro_sgml(%) {
  768.     my %args = %{$_[0]};
  769.     my ($parameter, $section);
  770.     my $count;
  772.     my $id = $args{'module'};
  773.     $id =~ s/[^A-Za-z0-9]/-/g;
  775.     # print out each section
  776.     $lineprefix="   ";
  777.     foreach $section (@{$args{'sectionlist'}}) {
  778. print "<refsect1>n <title>$section</title>n <para>n";
  779. if ($section =~ m/EXAMPLE/i) {
  780.     print "<example><para>n";
  781. }
  782. output_highlight($args{'sections'}{$section});
  783. if ($section =~ m/EXAMPLE/i) {
  784.     print "</para></example>n";
  785. }
  786. print " </para>n</refsect1>n";
  787.     }
  789.     print "nn";
  790. }
  792. # output in sgml DocBook
  793. sub output_function_gnome {
  794.     my %args = %{$_[0]};
  795.     my ($parameter, $section);
  796.     my $count;
  797.     my $id;
  799.     $id = $args{'module'}."-".$args{'function'};
  800.     $id =~ s/[^A-Za-z0-9]/-/g;
  802.     print "<sect2>n";
  803.     print " <title id="$id">".$args{'function'}."</title>n";
  805.     print "  <funcsynopsis>n";
  806.     print "   <funcdef>".$args{'functiontype'}." ";
  807.     print "<function>".$args{'function'}." ";
  808.     print "</function></funcdef>n";
  810.     $count = 0;
  811.     if ($#{$args{'parameterlist'}} >= 0) {
  812. foreach $parameter (@{$args{'parameterlist'}}) {
  813.     $type = $args{'parametertypes'}{$parameter};
  814.     if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  815. # pointer-to-function
  816. print "   <paramdef>$1 <parameter>$parameter</parameter>)n";
  817. print "     <funcparams>$2</funcparams></paramdef>n";
  818.     } else {
  819. print "   <paramdef>".$type;
  820. print " <parameter>$parameter</parameter></paramdef>n";
  821.     }
  822. }
  823.     } else {
  824. print "  <void>n";
  825.     }
  826.     print "  </funcsynopsis>n";
  827.     if ($#{$args{'parameterlist'}} >= 0) {
  828. print " <informaltable pgwide="1" frame="none" role="params">n";
  829. print "<tgroup cols="2">n";
  830. print "<colspec colwidth="2*">n";
  831. print "<colspec colwidth="8*">n";
  832. print "<tbody>n";
  833. foreach $parameter (@{$args{'parameterlist'}}) {
  834.     print "  <row><entry align="right"><parameter>$parameter</parameter></entry>n";
  835.     print "   <entry>n";
  836.     $lineprefix="     ";
  837.     output_highlight($args{'parameterdescs'}{$parameter});
  838.     print "    </entry></row>n";
  839. }
  840. print " </tbody></tgroup></informaltable>n";
  841.     } else {
  842. print " <para>n  Nonen </para>n";
  843.     }
  845.     # print out each section
  846.     $lineprefix="   ";
  847.     foreach $section (@{$args{'sectionlist'}}) {
  848. print "<simplesect>n <title>$section</title>n";
  849. if ($section =~ m/EXAMPLE/i) {
  850.     print "<example><programlisting>n";
  851. } else {
  852. }
  853. print "<para>n";
  854. output_highlight($args{'sections'}{$section});
  855. print "</para>n";
  856. if ($section =~ m/EXAMPLE/i) {
  857.     print "</programlisting></example>n";
  858. } else {
  859. }
  860. print " </simplesect>n";
  861.     }
  863.     print "</sect2>nn";
  864. }
  866. ##
  867. # output function in man
  868. sub output_function_man(%) {
  869.     my %args = %{$_[0]};
  870.     my ($parameter, $section);
  871.     my $count;
  873.     print ".TH "$args{'module'}" 9 "$args{'function'}" "$man_date" "API Manual" LINUXn";
  875.     print ".SH NAMEn";
  876.     print $args{'function'}." \- ".$args{'purpose'}."n";
  878.     print ".SH SYNOPSISn";
  879.     print ".B "".$args{'functiontype'}."" ".$args{'function'}."n";
  880.     $count = 0;
  881.     my $parenth = "(";
  882.     my $post = ",";
  883.     foreach my $parameter (@{$args{'parameterlist'}}) {
  884. if ($count == $#{$args{'parameterlist'}}) {
  885.     $post = ");";
  886. }
  887. $type = $args{'parametertypes'}{$parameter};
  888. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  889.     # pointer-to-function
  890.     print ".BI "".$parenth.$1."" ".$parameter." ") (".$2.")".$post.""n";
  891. } else {
  892.     $type =~ s/([^*])$/$1 /;
  893.     print ".BI "".$parenth.$type."" ".$parameter." "".$post.""n";
  894. }
  895. $count++;
  896. $parenth = "";
  897.     }
  899.     print ".SH Argumentsn";
  900.     foreach $parameter (@{$args{'parameterlist'}}) {
  901. print ".IP "".$parameter."" 12n";
  902. output_highlight($args{'parameterdescs'}{$parameter});
  903.     }
  904.     foreach $section (@{$args{'sectionlist'}}) {
  905. print ".SH "$section"n";
  906. output_highlight($args{'sections'}{$section});
  907.     }
  908. }
  910. ##
  911. # output enum in man
  912. sub output_enum_man(%) {
  913.     my %args = %{$_[0]};
  914.     my ($parameter, $section);
  915.     my $count;
  917.     print ".TH "$args{'module'}" 9 "enum $args{'enum'}" "$man_date" "API Manual" LINUXn";
  919.     print ".SH NAMEn";
  920.     print "enum ".$args{'enum'}." \- ".$args{'purpose'}."n";
  922.     print ".SH SYNOPSISn";
  923.     print "enum ".$args{'enum'}." {n";
  924.     $count = 0;
  925.     foreach my $parameter (@{$args{'parameterlist'}}) {
  926.         print ".brn.BI "    $parameter"n";
  927. if ($count == $#{$args{'parameterlist'}}) {
  928.     print "n};n";
  929.     last;
  930. }
  931. else {
  932.     print ", n.brn";
  933. }
  934. $count++;
  935.     }
  937.     print ".SH Constantsn";
  938.     foreach $parameter (@{$args{'parameterlist'}}) {
  939. print ".IP "".$parameter."" 12n";
  940. output_highlight($args{'parameterdescs'}{$parameter});
  941.     }
  942.     foreach $section (@{$args{'sectionlist'}}) {
  943. print ".SH "$section"n";
  944. output_highlight($args{'sections'}{$section});
  945.     }
  946. }
  948. ##
  949. # output struct in man
  950. sub output_struct_man(%) {
  951.     my %args = %{$_[0]};
  952.     my ($parameter, $section);
  954.     print ".TH "$args{'module'}" 9 "".$args{'type'}." ".$args{'struct'}."" "$man_date" "API Manual" LINUXn";
  956.     print ".SH NAMEn";
  957.     print $args{'type'}." ".$args{'struct'}." \- ".$args{'purpose'}."n";
  959.     print ".SH SYNOPSISn";
  960.     print $args{'type'}." ".$args{'struct'}." {n";
  962.     foreach my $parameter (@{$args{'parameterlist'}}) {
  963.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  964. print "n.brn";
  965. $type = $args{'parametertypes'}{$parameter};
  966. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  967.     # pointer-to-function
  968.     print ".BI "    ".$1."" ".$parameter." ") (".$2.")".""n;n";
  969. } elsif ($type =~ m/^(.*?)s*(:.*)/) {
  970.     print ".BI "    ".$1."" ".$parameter.$2." "".""n;n";
  971. } else {
  972.     $type =~ s/([^*])$/$1 /;
  973.     print ".BI "    ".$type."" ".$parameter." "".""n;n";
  974. }
  975. print "n.brn";
  976.     }
  977.     print "};n.brn";
  979.     print ".SH Argumentsn";
  980.     foreach $parameter (@{$args{'parameterlist'}}) {
  981.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  982. print ".IP "".$parameter."" 12n";
  983. output_highlight($args{'parameterdescs'}{$parameter});
  984.     }
  985.     foreach $section (@{$args{'sectionlist'}}) {
  986. print ".SH "$section"n";
  987. output_highlight($args{'sections'}{$section});
  988.     }
  989. }
  991. ##
  992. # output typedef in man
  993. sub output_typedef_man(%) {
  994.     my %args = %{$_[0]};
  995.     my ($parameter, $section);
  997.     print ".TH "$args{'module'}" 9 "$args{'typedef'}" "$man_date" "API Manual" LINUXn";
  999.     print ".SH NAMEn";
  1000.     print "typedef ".$args{'typedef'}." \- ".$args{'purpose'}."n";
  1002.     foreach $section (@{$args{'sectionlist'}}) {
  1003. print ".SH "$section"n";
  1004. output_highlight($args{'sections'}{$section});
  1005.     }
  1006. }
  1008. sub output_intro_man(%) {
  1009.     my %args = %{$_[0]};
  1010.     my ($parameter, $section);
  1011.     my $count;
  1013.     print ".TH "$args{'module'}" 9 "$args{'module'}" "$man_date" "API Manual" LINUXn";
  1015.     foreach $section (@{$args{'sectionlist'}}) {
  1016. print ".SH "$section"n";
  1017. output_highlight($args{'sections'}{$section});
  1018.     }
  1019. }
  1021. ##
  1022. # output in text
  1023. sub output_function_text(%) {
  1024.     my %args = %{$_[0]};
  1025.     my ($parameter, $section);
  1027.     print "Function:nn";
  1028.     my $start=$args{'functiontype'}." ".$args{'function'}." (";
  1029.     print $start;
  1030.     my $count = 0;
  1031.     foreach my $parameter (@{$args{'parameterlist'}}) {
  1032. $type = $args{'parametertypes'}{$parameter};
  1033. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  1034.     # pointer-to-function
  1035.     print $1.$parameter.") (".$2;
  1036. } else {
  1037.     print $type." ".$parameter;
  1038. }
  1039. if ($count != $#{$args{'parameterlist'}}) {
  1040.     $count++;
  1041.     print ",n";
  1042.     print " " x length($start);
  1043. } else {
  1044.     print ");nn";
  1045. }
  1046.     }
  1048.     print "Arguments:nn";
  1049.     foreach $parameter (@{$args{'parameterlist'}}) {
  1050. print $parameter."nt".$args{'parameterdescs'}{$parameter}."n";
  1051.     }
  1052.     output_section_text(@_);
  1053. }
  1055. #output sections in text
  1056. sub output_section_text(%) {
  1057.     my %args = %{$_[0]};
  1058.     my $section;
  1060.     print "n";
  1061.     foreach $section (@{$args{'sectionlist'}}) {
  1062. print "$section:nn";
  1063. output_highlight($args{'sections'}{$section});
  1064.     }  
  1065.     print "nn";
  1066. }
  1068. # output enum in text
  1069. sub output_enum_text(%) {
  1070.     my %args = %{$_[0]};
  1071.     my ($parameter);
  1072.     my $count;
  1073.     print "Enum:nn";
  1075.     print "enum ".$args{'enum'}." {n";
  1076.     $count = 0;
  1077.     foreach $parameter (@{$args{'parameterlist'}}) {
  1078.         print "t$parameter";
  1079. if ($count != $#{$args{'parameterlist'}}) {
  1080.     $count++;
  1081.     print ",";
  1082. }
  1083. print "n";
  1084.     }
  1085.     print "};nn";
  1087.     print "Constants:nn";
  1088.     foreach $parameter (@{$args{'parameterlist'}}) {
  1089. print "$parameternt";
  1090. print $args{'parameterdescs'}{$parameter}."n";
  1091.     }
  1093.     output_section_text(@_);
  1094. }
  1096. # output typedef in text
  1097. sub output_typedef_text(%) {
  1098.     my %args = %{$_[0]};
  1099.     my ($parameter);
  1100.     my $count;
  1101.     print "Typedef:nn";
  1103.     print "typedef ".$args{'typedef'}."n";
  1104.     output_section_text(@_);
  1105. }
  1107. # output struct as text
  1108. sub output_struct_text(%) {
  1109.     my %args = %{$_[0]};
  1110.     my ($parameter);
  1112.     print $args{'type'}." ".$args{'struct'}.":nn";
  1113.     print $args{'type'}." ".$args{'struct'}." {n";
  1114.     foreach $parameter (@{$args{'parameterlist'}}) {
  1115.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  1116. $type = $args{'parametertypes'}{$parameter};
  1117. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  1118.     # pointer-to-function
  1119.     print "t$1 $parameter) ($2);n";
  1120. } elsif ($type =~ m/^(.*?)s*(:.*)/) {
  1121.     print "t$1 $parameter$2;n";
  1122. } else {
  1123.     print "t".$type." ".$parameter.";n";
  1124. }
  1125.     }
  1126.     print "};nn";
  1128.     print "Members:nn";
  1129.     foreach $parameter (@{$args{'parameterlist'}}) {
  1130.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  1131. print "$parameternt";
  1132. print $args{'parameterdescs'}{$parameter}."n";
  1133.     }
  1134.     print "n";
  1135.     output_section_text(@_);
  1136. }
  1138. sub output_intro_text(%) {
  1139.     my %args = %{$_[0]};
  1140.     my ($parameter, $section);
  1142.     foreach $section (@{$args{'sectionlist'}}) {
  1143. print " $section:n";
  1144. print "    -> ";
  1145. output_highlight($args{'sections'}{$section});
  1146.     }
  1147. }
  1149. ##
  1150. # generic output function for typedefs
  1151. sub output_declaration {
  1152.     no strict 'refs';
  1153.     my $name = shift;
  1154.     my $functype = shift;
  1155.     my $func = "output_${functype}_$output_mode";
  1156.     if (($function_only==0) || 
  1157. ( $function_only == 1 && defined($function_table{$name})) || 
  1158. ( $function_only == 2 && !defined($function_table{$name})))
  1159.     {
  1160.         &$func(@_);
  1161.     }
  1162. }
  1164. ##
  1165. # generic output function - calls the right one based
  1166. # on current output mode.
  1167. sub output_intro {
  1168.     no strict 'refs';
  1169.     my $func = "output_intro_".$output_mode;
  1170.     &$func(@_);
  1171. }
  1173. ##
  1174. # takes a declaration (struct, union, enum, typedef) and 
  1175. # invokes the right handler. NOT called for functions.
  1176. sub dump_declaration($$) {
  1177.     no strict 'refs';
  1178.     my ($prototype, $file) = @_;
  1179.     my $func = "dump_".$decl_type;
  1180.     &$func(@_);
  1181. }
  1183. sub dump_union($$) {
  1184.     dump_struct(@_);
  1185. }
  1187. sub dump_struct($$) {
  1188.     my $x = shift;
  1189.     my $file = shift;
  1191.     if ($x =~/(struct|union)s+(w+)s*{(.*)}/) {
  1192.         $declaration_name = $2;
  1193.         my $members = $3;
  1195. # ignore embedded structs or unions
  1196. $members =~ s/{.*}//g;
  1198. create_parameterlist($members, ';');
  1200. output_declaration($declaration_name,
  1201.    'struct',
  1202.    {'struct' => $declaration_name,
  1203.     'module' => $modulename,
  1204.     'parameterlist' => @parameterlist,
  1205.     'parameterdescs' => %parameterdescs,
  1206.     'parametertypes' => %parametertypes,
  1207.     'sectionlist' => @sectionlist,
  1208.     'sections' => %sections,
  1209.     'purpose' => $declaration_purpose,
  1210.     'type' => $decl_type
  1211.    });
  1212.     }
  1213.     else {
  1214.         print STDERR "Cannot parse struct or union!n";
  1215.     }
  1216. }
  1218. sub dump_enum($$) {
  1219.     my $x = shift;
  1220.     my $file = shift;
  1222.     if ($x =~ /enums+(w+)s*{(.*)}/) {
  1223.         $declaration_name = $1;
  1224.         my $members = $2;
  1226. foreach my $arg (split ',', $members) {
  1227.     $arg =~ s/^s*(w+).*/$1/;
  1228.     push @parameterlist, $arg;
  1229.     if (!$parameterdescs{$arg}) {
  1230.         $parameterdescs{$arg} = $undescribed;
  1231.         print STDERR "Warning($file:$.): Enum value '$arg' ".
  1232.     "described in enum '$declaration_name'n";
  1233.     }
  1235. }
  1237. output_declaration($declaration_name,
  1238.    'enum',
  1239.    {'enum' => $declaration_name,
  1240.     'module' => $modulename,
  1241.     'parameterlist' => @parameterlist,
  1242.     'parameterdescs' => %parameterdescs,
  1243.     'sectionlist' => @sectionlist,
  1244.     'sections' => %sections,
  1245.     'purpose' => $declaration_purpose
  1246.    });
  1247.     }
  1248.     else {
  1249.         print STDERR "Cannot parse enum!n";
  1250.     }
  1251. }
  1253. sub dump_typedef($$) {
  1254.     my $x = shift;
  1255.     my $file = shift;
  1257.     while (($x =~ /(*.)s*;$/) || ($x =~ /[*.]s*;$/)) {
  1258.         $x =~ s/(*.)s*;$/;/;
  1259. $x =~ s/[*.]s*;$/;/;
  1260.     }
  1262.     if ($x =~ /typedef.*s+(w+)s*;/) {
  1263.         $declaration_name = $1;
  1265. output_declaration($declaration_name,
  1266.    'typedef',
  1267.    {'typedef' => $declaration_name,
  1268.     'module' => $modulename,
  1269.     'sectionlist' => @sectionlist,
  1270.     'sections' => %sections,
  1271.     'purpose' => $declaration_purpose
  1272.    });
  1273.     }
  1274.     else {
  1275.         print STDERR "Cannot parse typedef!n";
  1276.     }
  1277. }
  1279. sub create_parameterlist($$) {
  1280.     my $args = shift;
  1281.     my $splitter = shift;
  1282.     my $type;
  1283.     my $param;
  1285.     while ($args =~ /(([^),]+),/) {
  1286.         $args =~ s/(([^),]+),/$1#/g;
  1287.     }
  1288.     
  1289.     foreach my $arg (split($splitter, $args)) {
  1290.         # strip leading/trailing spaces
  1291.         $arg =~ s/^s*//;
  1292. $arg =~ s/s*$//;
  1293. $arg =~ s/s+/ /;
  1295. if ($arg =~ m/(/) {
  1296.     # pointer-to-function
  1297.     $arg =~ tr/#/,/;
  1298.     $arg =~ m/[^(]+(*([^)]+))/;
  1299.     $param = $1;
  1300.     $type = $arg;
  1301.     $type =~ s/([^(]+(*)$param/$1/;
  1302. } else {
  1303.     # evil magic to get fixed array parameters to work
  1304.     $arg =~ s/(.+s+)(.+)[.*/$1* $2/;
  1305.     my @args = split('s', $arg);
  1307.     $param = pop @args;
  1308.     if ($param =~ m/^(*+)(.*)/) {
  1309.         $param = $2;
  1310. push @args, $1;
  1311.     } 
  1312.     elsif ($param =~ m/(.*?)s*:s*(d+)/) {
  1313.         $param = $1;
  1314.         push @args, ":$2";
  1315.     }
  1316.     $type = join " ", @args;
  1317. }
  1319. if ($type eq "" && $param eq "...")
  1320. {
  1321.     $type="...";
  1322.     $param="...";
  1323.     $parameterdescs{"..."} = "variable arguments";
  1324. }
  1325. elsif ($type eq "" && ($param eq "" or $param eq "void"))
  1326. {
  1327.     $type="";
  1328.     $param="void";
  1329.     $parameterdescs{void} = "no arguments";
  1330. }
  1331. if (defined $type && $type && !defined $parameterdescs{$param}) {
  1332.     $parameterdescs{$param} = $undescribed;
  1334.     if (($type eq 'function') || ($type eq 'enum')) {
  1335.         print STDERR "Warning($file:$.): Function parameter ".
  1336.     "or member '$param' not " .
  1337.     "described in '$declaration_name'n";
  1338.     }
  1339.     ++$errors;
  1340.         }
  1342. push @parameterlist, $param;
  1343. $parametertypes{$param} = $type;
  1344.     }
  1345. }
  1347. ##
  1348. # takes a function prototype and the name of the current file being
  1349. # processed and spits out all the details stored in the global
  1350. # arrays/hashes.
  1351. sub dump_function($$) {
  1352.     my $prototype = shift;
  1353.     my $file = shift;
  1355.     $prototype =~ s/^static +//;
  1356.     $prototype =~ s/^extern +//;
  1357.     $prototype =~ s/^inline +//;
  1358.     $prototype =~ s/^__inline__ +//;
  1359.     $prototype =~ s/^#define +//; #ak added
  1361.     # Yes, this truly is vile.  We are looking for:
  1362.     # 1. Return type (may be nothing if we're looking at a macro)
  1363.     # 2. Function name
  1364.     # 3. Function parameters.
  1365.     #
  1366.     # All the while we have to watch out for function pointer parameters
  1367.     # (which IIRC is what the two sections are for), C types (these
  1368.     # regexps don't even start to express all the possibilities), and
  1369.     # so on.
  1370.     #
  1371.     # If you mess with these regexps, it's a good idea to check that
  1372.     # the following functions' documentation still comes out right:
  1373.     # - parport_register_device (function pointer parameters)
  1374.     # - atomic_set (macro)
  1375.     # - pci_match_device (long return type)
  1377.     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1378. $prototype =~ m/^(w+)s+([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1379. $prototype =~ m/^(w+s**)s*([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1380. $prototype =~ m/^(w+s+w+)s+([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1381. $prototype =~ m/^(w+s+w+s**)s*([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1382. $prototype =~ m/^(w+s+w+s+w+)s+([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1383. $prototype =~ m/^(w+s+w+s+w+s**)s*([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1384. $prototype =~ m/^()([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1385. $prototype =~ m/^(w+)s+([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1386. $prototype =~ m/^(w+s**)s*([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1387. $prototype =~ m/^(w+s+w+)s+([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1388. $prototype =~ m/^(w+s+w+s**)s*([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1389. $prototype =~ m/^(w+s+w+s+w+)s+([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1390. $prototype =~ m/^(w+s+w+s+w+s**)s*([a-zA-Z0-9_~:]+)s*(([^{]*))/)  {
  1391. $return_type = $1;
  1392. $declaration_name = $2;
  1393. my $args = $3;
  1395. create_parameterlist($args, ',');
  1396.     } else {
  1397. print STDERR "Error($.): cannot understand prototype: '$prototype'n";
  1398. ++$errors;
  1399. return;
  1400.     }
  1402.     output_declaration($declaration_name, 
  1403.        'function',
  1404.        {'function' => $declaration_name,
  1405. 'module' => $modulename,
  1406. 'functiontype' => $return_type,
  1407. 'parameterlist' => @parameterlist,
  1408. 'parameterdescs' => %parameterdescs,
  1409. 'parametertypes' => %parametertypes,
  1410. 'sectionlist' => @sectionlist,
  1411. 'sections' => %sections,
  1412. 'purpose' => $declaration_purpose
  1413.        });
  1414. }
  1416. sub process_file($);
  1418. # Read the file that maps relative names to absolute names for
  1419. # separate source and object directories and for shadow trees.
  1420. if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
  1421. my ($relname, $absname);
  1422. while(<SOURCE_MAP>) {
  1423. chop();
  1424. ($relname, $absname) = (split())[0..1];
  1425. $relname =~ s:^/+::;
  1426. $source_map{$relname} = $absname;
  1427. }
  1428. close(SOURCE_MAP);
  1429. }
  1431. if ($filelist) {
  1432. open(FLIST,"<$filelist") or die "Can't open file list $filelist";
  1433. while(<FLIST>) {
  1434. chop;
  1435. process_file($_);
  1436. }
  1437. }
  1439. foreach (@ARGV) {
  1440.     chomp;
  1441.     process_file($_);
  1442. }
  1444. exit($errors);
  1446. sub reset_state {
  1447.     $function = "";
  1448.     %constants = ();
  1449.     %parameterdescs = ();
  1450.     %parametertypes = ();
  1451.     @parameterlist = ();
  1452.     %sections = ();
  1453.     @sectionlist = ();
  1454.     $prototype = "";
  1455.     
  1456.     $state = 0;
  1457. }
  1459. sub process_state3_function($) { 
  1460.     my $x = shift;
  1462.     if ($x =~ m#s*/*s+MACDOCs*#io) {
  1463. # do nothing
  1464.     }
  1465.     elsif ($x =~ /([^{]*)/) {
  1466.         $prototype .= $1;
  1467.     }
  1468.     if (($x =~ /{/) || ($x =~ /#/) || ($x =~ /;/)) {
  1469.         $prototype =~ s@/*.*?*/@@gos; # strip comments.
  1470. $prototype =~ s@[rn]+@ @gos; # strip newlines/cr's.
  1471. $prototype =~ s@^s+@@gos; # strip leading spaces
  1472. dump_function($prototype,$file);
  1473. reset_state();
  1474.     }
  1475. }
  1477. sub process_state3_type($) { 
  1478.     my $x = shift;
  1480.     $x =~ s@/*.*?*/@@gos; # strip comments.
  1481.     $x =~ s@[rn]+@ @gos; # strip newlines/cr's.
  1482.     $x =~ s@^s+@@gos; # strip leading spaces
  1483.     $x =~ s@s+$@@gos; # strip trailing spaces
  1485.     while (1) {
  1486.         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
  1487.     $prototype .= $1 . $2;
  1488.     ($2 eq '{') && $brcount++;
  1489.     ($2 eq '}') && $brcount--;
  1490.     if (($2 eq ';') && ($brcount == 0)) {
  1491.         dump_declaration($prototype,$file);
  1492. reset_state();
  1493.         last;
  1494.     }
  1495.     $x = $3;
  1496.         } else {
  1497.     $prototype .= $x;
  1498.     last;
  1499. }
  1500.     }
  1501. }
  1503. sub process_file($) {
  1504.     my ($file) = @_;
  1505.     my $identifier;
  1506.     my $func;
  1508.     if (defined($source_map{$file})) {
  1509. $file = $source_map{$file};
  1510.     }
  1512.     if (!open(IN,"<$file")) {
  1513. print STDERR "Error: Cannot open file $filen";
  1514. ++$errors;
  1515. return;
  1516.     }
  1518.     while (<IN>) {
  1519. if ($state == 0) {
  1520.     if (/$doc_start/o) {
  1521. $state = 1; # next line is always the function name
  1522.     }
  1523. } elsif ($state == 1) { # this line is the function name (always)
  1524.     if (/$doc_block/o) {
  1525. $state = 4;
  1526. $contents = "";
  1527. if ( $1 eq "" ) {
  1528. $section = $section_intro;
  1529. } else {
  1530. $section = $1;
  1531. }
  1532.             }
  1533.     elsif (/$doc_decl/o) {
  1534. $identifier = $1;
  1535. if (/s*([ws]+?)s*-/) {
  1536.     $identifier = $1;
  1537. }
  1539. $state = 2;
  1540. if (/-(.*)/) {
  1541.     $declaration_purpose = $1;
  1542. } else {
  1543.     $declaration_purpose = "";
  1544. }
  1545. if ($identifier =~ m/^struct/) {
  1546.     $decl_type = 'struct';
  1547. } elsif ($identifier =~ m/^union/) {
  1548.     $decl_type = 'union';
  1549. } elsif ($identifier =~ m/^enum/) {
  1550.     $decl_type = 'enum';
  1551. } elsif ($identifier =~ m/^typedef/) {
  1552.     $decl_type = 'typedef';
  1553. } else {
  1554.     $decl_type = 'function';
  1555. }
  1557. if ($verbose) {
  1558.     print STDERR "Info($.): Scanning doc for $identifiern";
  1559. }
  1560.     } else {
  1561. print STDERR "WARN($.): Cannot understand $_ on line $.",
  1562. " - I thought it was a doc linen";
  1563. ++$errors;
  1564. $state = 0;
  1565.     }
  1566. } elsif ($state == 2) { # look for head: lines, and include content
  1567.     if (/$doc_sect/o) {
  1568. $newsection = $1;
  1569. $newcontents = $2;
  1571. if ($contents ne "") {
  1572.     $contents =~ s/&/\\\amp;/g;
  1573.     $contents =~ s/</\\\lt;/g;
  1574.     $contents =~ s/>/\\\gt;/g;
  1575.     dump_section($section, $contents);
  1576.     $section = $section_default;
  1577. }
  1579. $contents = $newcontents;
  1580. if ($contents ne "") {
  1581.     $contents .= "n";
  1582. }
  1583. $section = $newsection;
  1584.     } elsif (/$doc_end/) {
  1586. if ($contents ne "") {
  1587.     $contents =~ s/&/\\\amp;/g;
  1588.     $contents =~ s/</\\\lt;/g;
  1589.     $contents =~ s/>/\\\gt;/g;
  1590.     dump_section($section, $contents);
  1591.     $section = $section_default;
  1592.     $contents = "";
  1593. }
  1595. $prototype = "";
  1596. $state = 3;
  1597. $brcount = 0;
  1598. #     print STDERR "end of doc comment, looking for prototypen";
  1599.     } elsif (/$doc_content/) {
  1600. # miguel-style comment kludge, look for blank lines after
  1601. # @parameter line to signify start of description
  1602. if ($1 eq "" && 
  1603. ($section =~ m/^@/ || $section eq $section_context)) {
  1604.     $contents =~ s/&/\\\amp;/g;
  1605.     $contents =~ s/</\\\lt;/g;
  1606.     $contents =~ s/>/\\\gt;/g;
  1607.     dump_section($section, $contents);
  1608.     $section = $section_default;
  1609.     $contents = "";
  1610. } else {
  1611.     $contents .= $1."n";
  1612. }
  1613.     } else {
  1614. # i dont know - bad line?  ignore.
  1615. print STDERR "WARNING($.): bad line: $_"; 
  1616. ++$errors;
  1617.     }
  1618. } elsif ($state == 3) { # scanning for function { (end of prototype)
  1619.     if ($decl_type eq 'function') {
  1620.         process_state3_function($_);
  1621.     } else {
  1622.         process_state3_type($_);
  1623.     }
  1624. } elsif ($state == 4) {
  1625. # Documentation block
  1626.         if (/$doc_block/) {
  1627. dump_section($section, $contents);
  1628. output_intro({'sectionlist' => @sectionlist,
  1629.       'sections' => %sections });
  1630. $contents = "";
  1631. $function = "";
  1632. %constants = ();
  1633. %parameterdescs = ();
  1634. %parametertypes = ();
  1635. @parameterlist = ();
  1636. %sections = ();
  1637. @sectionlist = ();
  1638. $prototype = "";
  1639. if ( $1 eq "" ) {
  1640. $section = $section_intro;
  1641. } else {
  1642. $section = $1;
  1643. }
  1644.                 }
  1645. elsif (/$doc_end/)
  1646. {
  1647. dump_section($section, $contents);
  1648. output_intro({'sectionlist' => @sectionlist,
  1649.       'sections' => %sections });
  1650. $contents = "";
  1651. $function = "";
  1652. %constants = ();
  1653. %parameterdescs = ();
  1654. %parametertypes = ();
  1655. @parameterlist = ();
  1656. %sections = ();
  1657. @sectionlist = ();
  1658. $prototype = "";
  1659. $state = 0;
  1660. }
  1661. elsif (/$doc_content/)
  1662. {
  1663. if ( $1 eq "" )
  1664. {
  1665. $contents .= $blankline;
  1666. }
  1667. else
  1668. {
  1669. $contents .= $1 . "n";
  1670. }
  1671.          }
  1672.           }
  1673.     }
  1674. }