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

源码开发语言/平台
当前位置：首页 > 源码/资料 > Linux/Unix编程 > 查看源码
kernel-doc
资源名称：linux-2.4.20.tar.gz　[点击查看]
上传用户：jlfgdled
上传日期：2013-04-10
资源大小：33168k
文件大小：46k
源码类别：

Linux/Unix编程

开发平台：

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,$declaration_name,$return_type);
  237. my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
  239. # Generated docbook code is inserted in a template at a point where 
  240. # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
  241. # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
  242. # We keep track of number of generated entries and generate a dummy
  243. # if needs be to ensure the expanded template can be postprocessed
  244. # into html.
  245. my $section_counter = 0;
  247. my $lineprefix="";
  249. # states
  250. # 0 - normal code
  251. # 1 - looking for function name
  252. # 2 - scanning field start.
  253. # 3 - scanning prototype.
  254. # 4 - documentation block
  255. my $state;
  257. #declaration types: can be
  258. # 'function', 'struct', 'union', 'enum', 'typedef'
  259. my $decl_type;
  261. my $doc_special = "@%$&";
  263. my $doc_start = '^/**s*$'; # Allow whitespace at end of comment start.
  264. my $doc_end = '*/';
  265. my $doc_com = 's**s*';
  266. my $doc_decl = $doc_com.'(w+)';
  267. my $doc_sect = $doc_com.'(['.$doc_special.']?[w ]+):(.*)';
  268. my $doc_content = $doc_com.'(.*)';
  269. my $doc_block = $doc_com.'DOC:s*(.*)?';
  271. my %constants;
  272. my %parameterdescs;
  273. my @parameterlist;
  274. my %sections;
  275. my @sectionlist;
  277. my $contents = "";
  278. my $section_default = "Description"; # default section
  279. my $section_intro = "Introduction";
  280. my $section = $section_default;
  281. my $section_context = "Context";
  283. my $undescribed = "-- undescribed --";
  285. 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 "-man") {
  294. $output_mode = "man";
  295. %highlights = %highlights_man;
  296. $blankline = $blankline_man;
  297.     } elsif ($cmd eq "-text") {
  298. $output_mode = "text";
  299. %highlights = %highlights_text;
  300. $blankline = $blankline_text;
  301.     } elsif ($cmd eq "-docbook") {
  302. $output_mode = "sgml";
  303. %highlights = %highlights_sgml;
  304. $blankline = $blankline_sgml;
  305.     } elsif ($cmd eq "-gnome") {
  306. $output_mode = "gnome";
  307. %highlights = %highlights_gnome;
  308. $blankline = $blankline_gnome;
  309.     } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
  310. $modulename = shift @ARGV;
  311.     } elsif ($cmd eq "-function") { # to only output specific functions
  312. $function_only = 1;
  313. $function = shift @ARGV;
  314. $function_table{$function} = 1;
  315.     } elsif ($cmd eq "-nofunction") { # to only output specific functions
  316. $function_only = 2;
  317. $function = shift @ARGV;
  318. $function_table{$function} = 1;
  319.     } elsif ($cmd eq "-v") {
  320. $verbose = 1;
  321.     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
  322. usage();
  323.     } elsif ($cmd eq '-filelist') {
  324.     $filelist = shift @ARGV;
  325.     }
  326. }
  329. # generate a sequence of code that will splice in highlighting information
  330. # using the s// operator.
  331. my $dohighlight = "";
  332. foreach my $pattern (keys %highlights) {
  333. #    print "scanning pattern $pattern ($highlights{$pattern})n";
  334.     $dohighlight .=  "$contents =~ s:$pattern:$highlights{$pattern}:gs;n";
  335. }
  337. ##
  338. # dumps section contents to arrays/hashes intended for that purpose.
  339. #
  340. sub dump_section {
  341.     my $name = shift;
  342.     my $contents = join "n", @_;
  344.     if ($name =~ m/$type_constant/) {
  345. $name = $1;
  346. # print STDERR "constant section '$1' = '$contents'n";
  347. $constants{$name} = $contents;
  348.     } elsif ($name =~ m/$type_param/) {
  349. # print STDERR "parameter def '$1' = '$contents'n";
  350. $name = $1;
  351. $parameterdescs{$name} = $contents;
  352.     } else {
  353. # print STDERR "other section '$name' = '$contents'n";
  354. $sections{$name} = $contents;
  355. push @sectionlist, $name;
  356.     }
  357. }
  359. ##
  360. # output function
  361. #
  362. # parameterdescs, a hash.
  363. #  function => "function name"
  364. #  parameterlist => @list of parameters
  365. #  parameterdescs => %parameter descriptions
  366. #  sectionlist => @list of sections
  367. #  sections => %descriont descriptions
  368. #  
  370. sub output_highlight {
  371.     my $contents = join "n",@_;
  372.     my $line;
  374. #   DEBUG
  375. #   if (!defined $contents) {
  376. # use Carp;
  377. # confess "output_highlight got called with no args?n";
  378. #   }
  380.     eval $dohighlight;
  381.     die $@ if $@;
  382.     foreach $line (split "n", $contents) {
  383.       if ($line eq ""){
  384.     print $lineprefix, $blankline;
  385. } else {
  386.             $line =~ s/\\\/&/g;
  387.     print $lineprefix, $line;
  388. }
  389. print "n";
  390.     }
  391. }
  393. #output sections in html
  394. sub output_section_html(%) {
  395.     my %args = %{$_[0]};
  396.     my $section;
  398.     foreach $section (@{$args{'sectionlist'}}) {
  399. print "<h3>$section</h3>n";
  400. print "<blockquote>n";
  401. output_highlight($args{'sections'}{$section});
  402. print "</blockquote>n";
  403.     }  
  404. }
  406. # output enum in html
  407. sub output_enum_html(%) {
  408.     my %args = %{$_[0]};
  409.     my ($parameter);
  410.     my $count;
  411.     print "<h2>enum ".$args{'enum'}."</h2>n";
  413.     print "<b>enum ".$args{'enum'}."</b> {<br>n";
  414.     $count = 0;
  415.     foreach $parameter (@{$args{'parameterlist'}}) {
  416.         print " <b>".$parameter."</b>";
  417. if ($count != $#{$args{'parameterlist'}}) {
  418.     $count++;
  419.     print ",n";
  420. }
  421. print "<br>";
  422.     }
  423.     print "};<br>n";
  425.     print "<h3>Constants</h3>n";
  426.     print "<dl>n";
  427.     foreach $parameter (@{$args{'parameterlist'}}) {
  428. print "<dt><b>".$parameter."</b>n";
  429. print "<dd>";
  430. output_highlight($args{'parameterdescs'}{$parameter});
  431.     }
  432.     print "</dl>n";
  433.     output_section_html(@_);
  434.     print "<hr>n";
  435. }
  437. # output tyepdef in html
  438. sub output_typedef_html(%) {
  439.     my %args = %{$_[0]};
  440.     my ($parameter);
  441.     my $count;
  442.     print "<h2>typedef ".$args{'typedef'}."</h2>n";
  444.     print "<b>typedef ".$args{'typedef'}."</b>n";
  445.     output_section_html(@_);
  446.     print "<hr>n";
  447. }
  449. # output struct in html
  450. sub output_struct_html(%) {
  451.     my %args = %{$_[0]};
  452.     my ($parameter);
  454.     print "<h2>".$args{'type'}." ".$args{'struct'}."</h2>n";
  455.     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>n";
  456.     foreach $parameter (@{$args{'parameterlist'}}) {
  457.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  458. $type = $args{'parametertypes'}{$parameter};
  459. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  460.     # pointer-to-function
  461.     print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>n";
  462. } elsif ($type =~ m/^(.*?)s*(:.*)/) {
  463.     print " <i>$1</i> <b>$parameter</b>$2;<br>n";
  464. } else {
  465.     print " <i>$type</i> <b>$parameter</b>;<br>n";
  466. }
  467.     }
  468.     print "};<br>n";
  470.     print "<h3>Members</h3>n";
  471.     print "<dl>n";
  472.     foreach $parameter (@{$args{'parameterlist'}}) {
  473.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  474. print "<dt><b>".$parameter."</b>n";
  475. print "<dd>";
  476. output_highlight($args{'parameterdescs'}{$parameter});
  477.     }
  478.     print "</dl>n";
  479.     output_section_html(@_);
  480.     print "<hr>n";
  481. }
  483. # output function in html
  484. sub output_function_html(%) {
  485.     my %args = %{$_[0]};
  486.     my ($parameter, $section);
  487.     my $count;
  488.     print "<h2>Function</h2>n";
  490.     print "<i>".$args{'functiontype'}."</i>n";
  491.     print "<b>".$args{'function'}."</b>n";
  492.     print "(";
  493.     $count = 0;
  494.     foreach $parameter (@{$args{'parameterlist'}}) {
  495. $type = $args{'parametertypes'}{$parameter};
  496. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  497.     # pointer-to-function
  498.     print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
  499. } else {
  500.     print "<i>".$type."</i> <b>".$parameter."</b>";
  501. }
  502. if ($count != $#{$args{'parameterlist'}}) {
  503.     $count++;
  504.     print ",n";
  505. }
  506.     }
  507.     print ")n";
  509.     print "<h3>Arguments</h3>n";
  510.     print "<dl>n";
  511.     foreach $parameter (@{$args{'parameterlist'}}) {
  512.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  513. print "<dt><b>".$parameter."</b>n";
  514. print "<dd>";
  515. output_highlight($args{'parameterdescs'}{$parameter});
  516.     }
  517.     print "</dl>n";
  518.     output_section_html(@_);
  519.     print "<hr>n";
  520. }
  522. # output intro in html
  523. sub output_intro_html(%) {
  524.     my %args = %{$_[0]};
  525.     my ($parameter, $section);
  526.     my $count;
  528.     foreach $section (@{$args{'sectionlist'}}) {
  529. print "<h3>$section</h3>n";
  530. print "<ul>n";
  531. output_highlight($args{'sections'}{$section});
  532. print "</ul>n";
  533.     }
  534.     print "<hr>n";
  535. }
  537. sub output_section_sgml(%) {
  538.     my %args = %{$_[0]};
  539.     my $section;    
  540.     # print out each section
  541.     $lineprefix="   ";
  542.     foreach $section (@{$args{'sectionlist'}}) {
  543. print "<refsect1>n <title>$section</title>n <para>n";
  544. if ($section =~ m/EXAMPLE/i) {
  545.     print "<example><para>n";
  546. }
  547. output_highlight($args{'sections'}{$section});
  548. if ($section =~ m/EXAMPLE/i) {
  549.     print "</para></example>n";
  550. }
  551. print " </para>n</refsect1>n";
  552.     }
  553. }
  555. # output function in sgml DocBook
  556. sub output_function_sgml(%) {
  557.     my %args = %{$_[0]};
  558.     my ($parameter, $section);
  559.     my $count;
  560.     my $id;
  562.     $id = "API-".$args{'function'};
  563.     $id =~ s/[^A-Za-z0-9]/-/g;
  565.     print "<refentry>n";
  566.     print "<refmeta>n";
  567.     print "<refentrytitle><phrase id="$id">".$args{'function'}."</phrase></refentrytitle>n";
  568.     print "</refmeta>n";
  569.     print "<refnamediv>n";
  570.     print " <refname>".$args{'function'}."</refname>n";
  571.     print " <refpurpose>n";
  572.     print "  ";
  573.     output_highlight ($args{'purpose'});
  574.     print " </refpurpose>n";
  575.     print "</refnamediv>n";
  577.     print "<refsynopsisdiv>n";
  578.     print " <title>Synopsis</title>n";
  579.     print "  <funcsynopsis><funcprototype>n";
  580.     print "   <funcdef>".$args{'functiontype'}." ";
  581.     print "<function>".$args{'function'}." </function></funcdef>n";
  583.     $count = 0;
  584.     if ($#{$args{'parameterlist'}} >= 0) {
  585. foreach $parameter (@{$args{'parameterlist'}}) {
  586.     $type = $args{'parametertypes'}{$parameter};
  587.     if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  588. # pointer-to-function
  589. print "   <paramdef>$1<parameter>$parameter</parameter>)n";
  590. print "     <funcparams>$2</funcparams></paramdef>n";
  591.     } else {
  592. print "   <paramdef>".$type;
  593. print " <parameter>$parameter</parameter></paramdef>n";
  594.     }
  595. }
  596.     } else {
  597. print "  <void>n";
  598.     }
  599.     print "  </funcprototype></funcsynopsis>n";
  600.     print "</refsynopsisdiv>n";
  602.     # print parameters
  603.     print "<refsect1>n <title>Arguments</title>n";
  604.     if ($#{$args{'parameterlist'}} >= 0) {
  605. print " <variablelist>n";
  606. foreach $parameter (@{$args{'parameterlist'}}) {
  607.     print "  <varlistentry>n   <term><parameter>$parameter</parameter></term>n";
  608.     print "   <listitem>n    <para>n";
  609.     $lineprefix="     ";
  610.     output_highlight($args{'parameterdescs'}{$parameter});
  611.     print "    </para>n   </listitem>n  </varlistentry>n";
  612. }
  613. print " </variablelist>n";
  614.     } else {
  615. print " <para>n  Nonen </para>n";
  616.     }
  617.     print "</refsect1>n";
  619.     output_section_sgml(@_);
  620.     print "</refentry>nn";
  621. }
  623. # output struct in sgml DocBook
  624. sub output_struct_sgml(%) {
  625.     my %args = %{$_[0]};
  626.     my ($parameter, $section);
  627.     my $id;
  629.     $id = "API-struct-".$args{'struct'};
  630.     $id =~ s/[^A-Za-z0-9]/-/g;
  632.     print "<refentry>n";
  633.     print "<refmeta>n";
  634.     print "<refentrytitle><phrase id="$id">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>n";
  635.     print "</refmeta>n";
  636.     print "<refnamediv>n";
  637.     print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>n";
  638.     print " <refpurpose>n";
  639.     print "  ";
  640.     output_highlight ($args{'purpose'});
  641.     print " </refpurpose>n";
  642.     print "</refnamediv>n";
  644.     print "<refsynopsisdiv>n";
  645.     print " <title>Synopsis</title>n";
  646.     print "  <programlisting>n";
  647.     print $args{'type'}." ".$args{'struct'}." {n";
  648.     foreach $parameter (@{$args{'parameterlist'}}) {
  649.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  650. $type = $args{'parametertypes'}{$parameter};
  651. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  652.     # pointer-to-function
  653.     print "  $1 $parameter ($2);n";
  654. } elsif ($type =~ m/^(.*?)s*(:.*)/) {
  655.     print "  $1 $parameter$2;n";
  656. } else {
  657.     print "  ".$type." ".$parameter.";n";
  658. }
  659.     }
  660.     print "};";
  661.     print "  </programlisting>n";
  662.     print "</refsynopsisdiv>n";
  664.     print " <refsect1>n";
  665.     print "  <title>Members</title>n";
  667.     print "  <variablelist>n";
  668.     foreach $parameter (@{$args{'parameterlist'}}) {
  669.       ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  670.       print "    <varlistentry>";
  671.       print "      <term>$parameter</term>n";
  672.       print "      <listitem><para>n";
  673.       output_highlight($args{'parameterdescs'}{$parameter});
  674.       print "      </para></listitem>n";
  675.       print "    </varlistentry>n";
  676.     }
  677.     print "  </variablelist>n";
  678.     print " </refsect1>n";
  680.     output_section_sgml(@_);
  682.     print "</refentry>nn";
  683. }
  685. # output enum in sgml DocBook
  686. sub output_enum_sgml(%) {
  687.     my %args = %{$_[0]};
  688.     my ($parameter, $section);
  689.     my $count;
  690.     my $id;
  692.     $id = "API-enum-".$args{'enum'};
  693.     $id =~ s/[^A-Za-z0-9]/-/g;
  695.     print "<refentry>n";
  696.     print "<refmeta>n";
  697.     print "<refentrytitle><phrase id="$id">enum ".$args{'enum'}."</phrase></refentrytitle>n";
  698.     print "</refmeta>n";
  699.     print "<refnamediv>n";
  700.     print " <refname>enum ".$args{'enum'}."</refname>n";
  701.     print " <refpurpose>n";
  702.     print "  ";
  703.     output_highlight ($args{'purpose'});
  704.     print " </refpurpose>n";
  705.     print "</refnamediv>n";
  707.     print "<refsynopsisdiv>n";
  708.     print " <title>Synopsis</title>n";
  709.     print "  <programlisting>n";
  710.     print "enum ".$args{'enum'}." {n";
  711.     $count = 0;
  712.     foreach $parameter (@{$args{'parameterlist'}}) {
  713.         print "  $parameter";
  714.         if ($count != $#{$args{'parameterlist'}}) {
  715.     $count++;
  716.     print ",";
  717.         }
  718. print "n";
  719.     }
  720.     print "};";
  721.     print "  </programlisting>n";
  722.     print "</refsynopsisdiv>n";
  724.     print "<refsect1>n";
  725.     print " <title>Constants</title>n";    
  726.     print "  <variablelist>n";
  727.     foreach $parameter (@{$args{'parameterlist'}}) {
  728.       print "    <varlistentry>";
  729.       print "      <term>$parameter</term>n";
  730.       print "      <listitem><para>n";
  731.       output_highlight($args{'parameterdescs'}{$parameter});
  732.       print "      </para></listitem>n";
  733.       print "    </varlistentry>n";
  734.     }
  735.     print "  </variablelist>n";
  736.     print "</refsect1>n";
  738.     output_section_sgml(@_);
  740.     print "</refentry>nn";
  741. }
  743. # output typedef in sgml DocBook
  744. sub output_typedef_sgml(%) {
  745.     my %args = %{$_[0]};
  746.     my ($parameter, $section);
  747.     my $id;
  749.     $id = "API-typedef-".$args{'typedef'};
  750.     $id =~ s/[^A-Za-z0-9]/-/g;
  752.     print "<refentry>n";
  753.     print "<refmeta>n";
  754.     print "<refentrytitle><phrase id="$id">typedef ".$args{'typedef'}."</phrase></refentrytitle>n";
  755.     print "</refmeta>n";
  756.     print "<refnamediv>n";
  757.     print " <refname>typedef ".$args{'typedef'}."</refname>n";
  758.     print " <refpurpose>n";
  759.     print "  ";
  760.     output_highlight ($args{'purpose'});
  761.     print " </refpurpose>n";
  762.     print "</refnamediv>n";
  764.     print "<refsynopsisdiv>n";
  765.     print " <title>Synopsis</title>n";
  766.     print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>n";
  767.     print "</refsynopsisdiv>n";
  769.     output_section_sgml(@_);
  771.     print "</refentry>nn";
  772. }
  774. # output in sgml DocBook
  775. sub output_intro_sgml(%) {
  776.     my %args = %{$_[0]};
  777.     my ($parameter, $section);
  778.     my $count;
  780.     my $id = $args{'module'};
  781.     $id =~ s/[^A-Za-z0-9]/-/g;
  783.     # print out each section
  784.     $lineprefix="   ";
  785.     foreach $section (@{$args{'sectionlist'}}) {
  786. print "<refsect1>n <title>$section</title>n <para>n";
  787. if ($section =~ m/EXAMPLE/i) {
  788.     print "<example><para>n";
  789. }
  790. output_highlight($args{'sections'}{$section});
  791. if ($section =~ m/EXAMPLE/i) {
  792.     print "</para></example>n";
  793. }
  794. print " </para>n</refsect1>n";
  795.     }
  797.     print "nn";
  798. }
  800. # output in sgml DocBook
  801. sub output_function_gnome {
  802.     my %args = %{$_[0]};
  803.     my ($parameter, $section);
  804.     my $count;
  805.     my $id;
  807.     $id = $args{'module'}."-".$args{'function'};
  808.     $id =~ s/[^A-Za-z0-9]/-/g;
  810.     print "<sect2>n";
  811.     print " <title id="$id">".$args{'function'}."</title>n";
  813.     print "  <funcsynopsis>n";
  814.     print "   <funcdef>".$args{'functiontype'}." ";
  815.     print "<function>".$args{'function'}." ";
  816.     print "</function></funcdef>n";
  818.     $count = 0;
  819.     if ($#{$args{'parameterlist'}} >= 0) {
  820. foreach $parameter (@{$args{'parameterlist'}}) {
  821.     $type = $args{'parametertypes'}{$parameter};
  822.     if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  823. # pointer-to-function
  824. print "   <paramdef>$1 <parameter>$parameter</parameter>)n";
  825. print "     <funcparams>$2</funcparams></paramdef>n";
  826.     } else {
  827. print "   <paramdef>".$type;
  828. print " <parameter>$parameter</parameter></paramdef>n";
  829.     }
  830. }
  831.     } else {
  832. print "  <void>n";
  833.     }
  834.     print "  </funcsynopsis>n";
  835.     if ($#{$args{'parameterlist'}} >= 0) {
  836. print " <informaltable pgwide="1" frame="none" role="params">n";
  837. print "<tgroup cols="2">n";
  838. print "<colspec colwidth="2*">n";
  839. print "<colspec colwidth="8*">n";
  840. print "<tbody>n";
  841. foreach $parameter (@{$args{'parameterlist'}}) {
  842.     print "  <row><entry align="right"><parameter>$parameter</parameter></entry>n";
  843.     print "   <entry>n";
  844.     $lineprefix="     ";
  845.     output_highlight($args{'parameterdescs'}{$parameter});
  846.     print "    </entry></row>n";
  847. }
  848. print " </tbody></tgroup></informaltable>n";
  849.     } else {
  850. print " <para>n  Nonen </para>n";
  851.     }
  853.     # print out each section
  854.     $lineprefix="   ";
  855.     foreach $section (@{$args{'sectionlist'}}) {
  856. print "<simplesect>n <title>$section</title>n";
  857. if ($section =~ m/EXAMPLE/i) {
  858.     print "<example><programlisting>n";
  859. } else {
  860. }
  861. print "<para>n";
  862. output_highlight($args{'sections'}{$section});
  863. print "</para>n";
  864. if ($section =~ m/EXAMPLE/i) {
  865.     print "</programlisting></example>n";
  866. } else {
  867. }
  868. print " </simplesect>n";
  869.     }
  871.     print "</sect2>nn";
  872. }
  874. ##
  875. # output function in man
  876. sub output_function_man(%) {
  877.     my %args = %{$_[0]};
  878.     my ($parameter, $section);
  879.     my $count;
  881.     print ".TH "$args{'function'}" 9 "$args{'function'}" "25 May 1998" "Kernel Hacker's Manual" LINUXn";
  883.     print ".SH NAMEn";
  884.     print $args{'function'}." \- ".$args{'purpose'}."n";
  886.     print ".SH SYNOPSISn";
  887.     print ".B "".$args{'functiontype'}."" ".$args{'function'}."n";
  888.     $count = 0;
  889.     my $parenth = "(";
  890.     my $post = ",";
  891.     foreach my $parameter (@{$args{'parameterlist'}}) {
  892. if ($count == $#{$args{'parameterlist'}}) {
  893.     $post = ");";
  894. }
  895. $type = $args{'parametertypes'}{$parameter};
  896. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  897.     # pointer-to-function
  898.     print ".BI "".$parenth.$1."" ".$parameter." ") (".$2.")".$post.""n";
  899. } else {
  900.     $type =~ s/([^*])$/$1 /;
  901.     print ".BI "".$parenth.$type."" ".$parameter." "".$post.""n";
  902. }
  903. $count++;
  904. $parenth = "";
  905.     }
  907.     print ".SH ARGUMENTSn";
  908.     foreach $parameter (@{$args{'parameterlist'}}) {
  909. print ".IP "".$parameter."" 12n";
  910. output_highlight($args{'parameterdescs'}{$parameter});
  911.     }
  912.     foreach $section (@{$args{'sectionlist'}}) {
  913. print ".SH "", uc $section, ""n";
  914. output_highlight($args{'sections'}{$section});
  915.     }
  916. }
  918. ##
  919. # output enum in man
  920. sub output_enum_man(%) {
  921.     my %args = %{$_[0]};
  922.     my ($parameter, $section);
  923.     my $count;
  925.     print ".TH "$args{'module'}" 9 "enum $args{'enum'}" "$man_date" "API Manual" LINUXn";
  927.     print ".SH NAMEn";
  928.     print "enum ".$args{'enum'}." \- ".$args{'purpose'}."n";
  930.     print ".SH SYNOPSISn";
  931.     print "enum ".$args{'enum'}." {n";
  932.     $count = 0;
  933.     foreach my $parameter (@{$args{'parameterlist'}}) {
  934.         print ".brn.BI "    $parameter"n";
  935. if ($count == $#{$args{'parameterlist'}}) {
  936.     print "n};n";
  937.     last;
  938. }
  939. else {
  940.     print ", n.brn";
  941. }
  942. $count++;
  943.     }
  945.     print ".SH Constantsn";
  946.     foreach $parameter (@{$args{'parameterlist'}}) {
  947. print ".IP "".$parameter."" 12n";
  948. output_highlight($args{'parameterdescs'}{$parameter});
  949.     }
  950.     foreach $section (@{$args{'sectionlist'}}) {
  951. print ".SH "$section"n";
  952. output_highlight($args{'sections'}{$section});
  953.     }
  954. }
  956. ##
  957. # output struct in man
  958. sub output_struct_man(%) {
  959.     my %args = %{$_[0]};
  960.     my ($parameter, $section);
  962.     print ".TH "$args{'module'}" 9 "".$args{'type'}." ".$args{'struct'}."" "$man_date" "API Manual" LINUXn";
  964.     print ".SH NAMEn";
  965.     print $args{'type'}." ".$args{'struct'}." \- ".$args{'purpose'}."n";
  967.     print ".SH SYNOPSISn";
  968.     print $args{'type'}." ".$args{'struct'}." {n";
  970.     foreach my $parameter (@{$args{'parameterlist'}}) {
  971.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  972. print "n.brn";
  973. $type = $args{'parametertypes'}{$parameter};
  974. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  975.     # pointer-to-function
  976.     print ".BI "    ".$1."" ".$parameter." ") (".$2.")".""n;n";
  977. } elsif ($type =~ m/^(.*?)s*(:.*)/) {
  978.     print ".BI "    ".$1."" ".$parameter.$2." "".""n;n";
  979. } else {
  980.     $type =~ s/([^*])$/$1 /;
  981.     print ".BI "    ".$type."" ".$parameter." "".""n;n";
  982. }
  983. print "n.brn";
  984.     }
  985.     print "};n.brn";
  987.     print ".SH Argumentsn";
  988.     foreach $parameter (@{$args{'parameterlist'}}) {
  989.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  990. print ".IP "".$parameter."" 12n";
  991. output_highlight($args{'parameterdescs'}{$parameter});
  992.     }
  993.     foreach $section (@{$args{'sectionlist'}}) {
  994. print ".SH "$section"n";
  995. output_highlight($args{'sections'}{$section});
  996.     }
  997. }
  999. ##
  1000. # output typedef in man
  1001. sub output_typedef_man(%) {
  1002.     my %args = %{$_[0]};
  1003.     my ($parameter, $section);
  1005.     print ".TH "$args{'module'}" 9 "$args{'typedef'}" "$man_date" "API Manual" LINUXn";
  1007.     print ".SH NAMEn";
  1008.     print "typedef ".$args{'typedef'}." \- ".$args{'purpose'}."n";
  1010.     foreach $section (@{$args{'sectionlist'}}) {
  1011. print ".SH "$section"n";
  1012. output_highlight($args{'sections'}{$section});
  1013.     }
  1014. }
  1016. sub output_intro_man(%) {
  1017.     my %args = %{$_[0]};
  1018.     my ($parameter, $section);
  1019.     my $count;
  1021.     print ".TH "$args{'module'}" 9 "$args{'module'}" "$man_date" "API Manual" LINUXn";
  1023.     foreach $section (@{$args{'sectionlist'}}) {
  1024. print ".SH "$section"n";
  1025. output_highlight($args{'sections'}{$section});
  1026.     }
  1027. }
  1029. ##
  1030. # output in text
  1031. sub output_function_text(%) {
  1032.     my %args = %{$_[0]};
  1033.     my ($parameter, $section);
  1035.     print "Function:nn";
  1036.     my $start=$args{'functiontype'}." ".$args{'function'}." (";
  1037.     print $start;
  1038.     my $count = 0;
  1039.     foreach my $parameter (@{$args{'parameterlist'}}) {
  1040. $type = $args{'parametertypes'}{$parameter};
  1041. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  1042.     # pointer-to-function
  1043.     print $1.$parameter.") (".$2;
  1044. } else {
  1045.     print $type." ".$parameter;
  1046. }
  1047. if ($count != $#{$args{'parameterlist'}}) {
  1048.     $count++;
  1049.     print ",n";
  1050.     print " " x length($start);
  1051. } else {
  1052.     print ");nn";
  1053. }
  1054.     }
  1056.     print "Arguments:nn";
  1057.     foreach $parameter (@{$args{'parameterlist'}}) {
  1058. print $parameter."nt".$args{'parameterdescs'}{$parameter}."n";
  1059.     }
  1060.     output_section_text(@_);
  1061. }
  1063. #output sections in text
  1064. sub output_section_text(%) {
  1065.     my %args = %{$_[0]};
  1066.     my $section;
  1068.     print "n";
  1069.     foreach $section (@{$args{'sectionlist'}}) {
  1070. print "$section:nn";
  1071. output_highlight($args{'sections'}{$section});
  1072.     }  
  1073.     print "nn";
  1074. }
  1076. # output enum in text
  1077. sub output_enum_text(%) {
  1078.     my %args = %{$_[0]};
  1079.     my ($parameter);
  1080.     my $count;
  1081.     print "Enum:nn";
  1083.     print "enum ".$args{'enum'}." {n";
  1084.     $count = 0;
  1085.     foreach $parameter (@{$args{'parameterlist'}}) {
  1086.         print "t$parameter";
  1087. if ($count != $#{$args{'parameterlist'}}) {
  1088.     $count++;
  1089.     print ",";
  1090. }
  1091. print "n";
  1092.     }
  1093.     print "};nn";
  1095.     print "Constants:nn";
  1096.     foreach $parameter (@{$args{'parameterlist'}}) {
  1097. print "$parameternt";
  1098. print $args{'parameterdescs'}{$parameter}."n";
  1099.     }
  1101.     output_section_text(@_);
  1102. }
  1104. # output typedef in text
  1105. sub output_typedef_text(%) {
  1106.     my %args = %{$_[0]};
  1107.     my ($parameter);
  1108.     my $count;
  1109.     print "Typedef:nn";
  1111.     print "typedef ".$args{'typedef'}."n";
  1112.     output_section_text(@_);
  1113. }
  1115. # output struct as text
  1116. sub output_struct_text(%) {
  1117.     my %args = %{$_[0]};
  1118.     my ($parameter);
  1120.     print $args{'type'}." ".$args{'struct'}.":nn";
  1121.     print $args{'type'}." ".$args{'struct'}." {n";
  1122.     foreach $parameter (@{$args{'parameterlist'}}) {
  1123.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  1124. $type = $args{'parametertypes'}{$parameter};
  1125. if ($type =~ m/([^(]*(*)s*)s*(([^)]*))/) {
  1126.     # pointer-to-function
  1127.     print "t$1 $parameter) ($2);n";
  1128. } elsif ($type =~ m/^(.*?)s*(:.*)/) {
  1129.     print "t$1 $parameter$2;n";
  1130. } else {
  1131.     print "t".$type." ".$parameter.";n";
  1132. }
  1133.     }
  1134.     print "};nn";
  1136.     print "Members:nn";
  1137.     foreach $parameter (@{$args{'parameterlist'}}) {
  1138.         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
  1139. print "$parameternt";
  1140. print $args{'parameterdescs'}{$parameter}."n";
  1141.     }
  1142.     print "n";
  1143.     output_section_text(@_);
  1144. }
  1146. sub output_intro_text(%) {
  1147.     my %args = %{$_[0]};
  1148.     my ($parameter, $section);
  1150.     foreach $section (@{$args{'sectionlist'}}) {
  1151. print " $section:n";
  1152. print "    -> ";
  1153. output_highlight($args{'sections'}{$section});
  1154.     }
  1155. }
  1157. ##
  1158. # generic output function for typedefs
  1159. sub output_declaration {
  1160.     no strict 'refs';
  1161.     my $name = shift;
  1162.     my $functype = shift;
  1163.     my $func = "output_${functype}_$output_mode";
  1164.     if (($function_only==0) || 
  1165. ( $function_only == 1 && defined($function_table{$name})) || 
  1166. ( $function_only == 2 && !defined($function_table{$name})))
  1167.     {
  1168.         &$func(@_);
  1169. $section_counter++;
  1170.     }
  1171. }
  1173. ##
  1174. # generic output function - calls the right one based
  1175. # on current output mode.
  1176. sub output_intro {
  1177.     no strict 'refs';
  1178.     my $func = "output_intro_".$output_mode;
  1179.     &$func(@_);
  1180.     $section_counter++;
  1181. }
  1183. ##
  1184. # takes a declaration (struct, union, enum, typedef) and 
  1185. # invokes the right handler. NOT called for functions.
  1186. sub dump_declaration($$) {
  1187.     no strict 'refs';
  1188.     my ($prototype, $file) = @_;
  1189.     my $func = "dump_".$decl_type;
  1190.     &$func(@_);
  1191. }
  1193. sub dump_union($$) {
  1194.     dump_struct(@_);
  1195. }
  1197. sub dump_struct($$) {
  1198.     my $x = shift;
  1199.     my $file = shift;
  1201.     if ($x =~/(struct|union)s+(w+)s*{(.*)}/) {
  1202.         $declaration_name = $2;
  1203.         my $members = $3;
  1205. # ignore embedded structs or unions
  1206. $members =~ s/{.*}//g;
  1208. create_parameterlist($members, ';', $file);
  1210. output_declaration($declaration_name,
  1211.    'struct',
  1212.    {'struct' => $declaration_name,
  1213.     'module' => $modulename,
  1214.     'parameterlist' => @parameterlist,
  1215.     'parameterdescs' => %parameterdescs,
  1216.     'parametertypes' => %parametertypes,
  1217.     'sectionlist' => @sectionlist,
  1218.     'sections' => %sections,
  1219.     'purpose' => $declaration_purpose,
  1220.     'type' => $decl_type
  1221.    });
  1222.     }
  1223.     else {
  1224.         print STDERR "Error(${file}:$.): Cannot parse struct or union!n";
  1225. ++$errors;
  1226.     }
  1227. }
  1229. sub dump_enum($$) {
  1230.     my $x = shift;
  1231.     my $file = shift;
  1233.     if ($x =~ /enums+(w+)s*{(.*)}/) {
  1234.         $declaration_name = $1;
  1235.         my $members = $2;
  1237. foreach my $arg (split ',', $members) {
  1238.     $arg =~ s/^s*(w+).*/$1/;
  1239.     push @parameterlist, $arg;
  1240.     if (!$parameterdescs{$arg}) {
  1241.         $parameterdescs{$arg} = $undescribed;
  1242.         print STDERR "Warning(${file}:$.): Enum value '$arg' ".
  1243.     "not described in enum '$declaration_name'n";
  1244.     }
  1246. }
  1248. output_declaration($declaration_name,
  1249.    'enum',
  1250.    {'enum' => $declaration_name,
  1251.     'module' => $modulename,
  1252.     'parameterlist' => @parameterlist,
  1253.     'parameterdescs' => %parameterdescs,
  1254.     'sectionlist' => @sectionlist,
  1255.     'sections' => %sections,
  1256.     'purpose' => $declaration_purpose
  1257.    });
  1258.     }
  1259.     else {
  1260.         print STDERR "Error(${file}:$.): Cannot parse enum!n";
  1261. ++$errors;
  1262.     }
  1263. }
  1265. sub dump_typedef($$) {
  1266.     my $x = shift;
  1267.     my $file = shift;
  1269.     while (($x =~ /(*.)s*;$/) || ($x =~ /[*.]s*;$/)) {
  1270.         $x =~ s/(*.)s*;$/;/;
  1271. $x =~ s/[*.]s*;$/;/;
  1272.     }
  1274.     if ($x =~ /typedef.*s+(w+)s*;/) {
  1275.         $declaration_name = $1;
  1277. output_declaration($declaration_name,
  1278.    'typedef',
  1279.    {'typedef' => $declaration_name,
  1280.     'module' => $modulename,
  1281.     'sectionlist' => @sectionlist,
  1282.     'sections' => %sections,
  1283.     'purpose' => $declaration_purpose
  1284.    });
  1285.     }
  1286.     else {
  1287.         print STDERR "Error(${file}:$.): Cannot parse typedef!n";
  1288. ++$errors;
  1289.     }
  1290. }
  1292. sub create_parameterlist($$$) {
  1293.     my $args = shift;
  1294.     my $splitter = shift;
  1295.     my $file = shift;
  1296.     my $type;
  1297.     my $param;
  1299.     while ($args =~ /(([^),]+),/) {
  1300.         $args =~ s/(([^),]+),/$1#/g;
  1301.     }
  1302.     
  1303.     foreach my $arg (split($splitter, $args)) {
  1304.         # strip leading/trailing spaces
  1305.         $arg =~ s/^s*//;
  1306. $arg =~ s/s*$//;
  1307. $arg =~ s/s+/ /;
  1309. if ($arg =~ m/(/) {
  1310.     # pointer-to-function
  1311.     $arg =~ tr/#/,/;
  1312.     $arg =~ m/[^(]+(*([^)]+))/;
  1313.     $param = $1;
  1314.     $type = $arg;
  1315.     $type =~ s/([^(]+(*)$param/$1/;
  1316. } else {
  1317.     # evil magic to get fixed array parameters to work
  1318.     $arg =~ s/(.+s+)(.+)[.*/$1* $2/;
  1319.     my @args = split('s', $arg);
  1321.     $param = pop @args;
  1322.     if ($param =~ m/^(*+)(.*)/) {
  1323.         $param = $2;
  1324. push @args, $1;
  1325.     } 
  1326.     elsif ($param =~ m/(.*?)s*:s*(d+)/) {
  1327.         $param = $1;
  1328.         push @args, ":$2";
  1329.     }
  1330.     $type = join " ", @args;
  1331. }
  1333. if ($type eq "" && $param eq "...")
  1334. {
  1335.     $type="...";
  1336.     $param="...";
  1337.     $parameterdescs{"..."} = "variable arguments";
  1338. }
  1339. elsif ($type eq "" && ($param eq "" or $param eq "void"))
  1340. {
  1341.     $type="";
  1342.     $param="void";
  1343.     $parameterdescs{void} = "no arguments";
  1344. }
  1345. if (defined $type && $type && !defined $parameterdescs{$param}) {
  1346.     $parameterdescs{$param} = $undescribed;
  1348.     if (($type eq 'function') || ($type eq 'enum')) {
  1349.         print STDERR "Warning(${file}:$.): Function parameter ".
  1350.     "or member '$param' not " .
  1351.     "described in '$declaration_name'n";
  1352.     }
  1353.     ++$errors;
  1354.         }
  1356. push @parameterlist, $param;
  1357. $parametertypes{$param} = $type;
  1358.     }
  1359. }
  1361. ##
  1362. # takes a function prototype and the name of the current file being
  1363. # processed and spits out all the details stored in the global
  1364. # arrays/hashes.
  1365. sub dump_function($$) {
  1366.     my $prototype = shift;
  1367.     my $file = shift;
  1369.     $prototype =~ s/^static +//;
  1370.     $prototype =~ s/^extern +//;
  1371.     $prototype =~ s/^inline +//;
  1372.     $prototype =~ s/^__inline__ +//;
  1373.     $prototype =~ s/^#define +//; #ak added
  1375.     # Yes, this truly is vile.  We are looking for:
  1376.     # 1. Return type (may be nothing if we're looking at a macro)
  1377.     # 2. Function name
  1378.     # 3. Function parameters.
  1379.     #
  1380.     # All the while we have to watch out for function pointer parameters
  1381.     # (which IIRC is what the two sections are for), C types (these
  1382.     # regexps don't even start to express all the possibilities), and
  1383.     # so on.
  1384.     #
  1385.     # If you mess with these regexps, it's a good idea to check that
  1386.     # the following functions' documentation still comes out right:
  1387.     # - parport_register_device (function pointer parameters)
  1388.     # - atomic_set (macro)
  1389.     # - pci_match_device (long return type)
  1391.     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1392. $prototype =~ m/^(w+)s+([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1393. $prototype =~ m/^(w+s**)s*([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1394. $prototype =~ m/^(w+s+w+)s+([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1395. $prototype =~ m/^(w+s+w+s**)s*([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1396. $prototype =~ m/^(w+s+w+s+w+)s+([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1397. $prototype =~ m/^(w+s+w+s+w+s**)s*([a-zA-Z0-9_~:]+)s*(([^(]*))/ ||
  1398. $prototype =~ m/^()([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1399. $prototype =~ m/^(w+)s+([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1400. $prototype =~ m/^(w+s**)s*([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1401. $prototype =~ m/^(w+s+w+)s+([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1402. $prototype =~ m/^(w+s+w+s**)s*([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1403. $prototype =~ m/^(w+s+w+s+w+)s+([a-zA-Z0-9_~:]+)s*(([^{]*))/ ||
  1404. $prototype =~ m/^(w+s+w+s+w+s**)s*([a-zA-Z0-9_~:]+)s*(([^{]*))/)  {
  1405. $return_type = $1;
  1406. $declaration_name = $2;
  1407. my $args = $3;
  1409. create_parameterlist($args, ',', $file);
  1410.     } else {
  1411. print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'n";
  1412. ++$errors;
  1413. return;
  1414.     }
  1416.     output_declaration($declaration_name, 
  1417.        'function',
  1418.        {'function' => $declaration_name,
  1419. 'module' => $modulename,
  1420. 'functiontype' => $return_type,
  1421. 'parameterlist' => @parameterlist,
  1422. 'parameterdescs' => %parameterdescs,
  1423. 'parametertypes' => %parametertypes,
  1424. 'sectionlist' => @sectionlist,
  1425. 'sections' => %sections,
  1426. 'purpose' => $declaration_purpose
  1427.        });
  1428. }
  1430. sub process_file($);
  1432. # Read the file that maps relative names to absolute names for
  1433. # separate source and object directories and for shadow trees.
  1434. if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
  1435. my ($relname, $absname);
  1436. while(<SOURCE_MAP>) {
  1437. chop();
  1438. ($relname, $absname) = (split())[0..1];
  1439. $relname =~ s:^/+::;
  1440. $source_map{$relname} = $absname;
  1441. }
  1442. close(SOURCE_MAP);
  1443. }
  1445. if ($filelist) {
  1446. open(FLIST,"<$filelist") or die "Can't open file list $filelist";
  1447. while(<FLIST>) {
  1448. chop;
  1449. process_file($_);
  1450. }
  1451. }
  1453. foreach (@ARGV) {
  1454.     chomp;
  1455.     process_file($_);
  1456. }
  1458. exit($errors);
  1460. sub reset_state {
  1461.     $function = "";
  1462.     %constants = ();
  1463.     %parameterdescs = ();
  1464.     %parametertypes = ();
  1465.     @parameterlist = ();
  1466.     %sections = ();
  1467.     @sectionlist = ();
  1468.     $prototype = "";
  1469.     
  1470.     $state = 0;
  1471. }
  1473. sub process_state3_function($$) { 
  1474.     my $x = shift;
  1475.     my $file = shift;
  1477.     if ($x =~ m#s*/*s+MACDOCs*#io) {
  1478. # do nothing
  1479.     }
  1480.     elsif ($x =~ /([^{]*)/) {
  1481.         $prototype .= $1;
  1482.     }
  1483.     if (($x =~ /{/) || ($x =~ /#/) || ($x =~ /;/)) {
  1484.         $prototype =~ s@/*.*?*/@@gos; # strip comments.
  1485. $prototype =~ s@[rn]+@ @gos; # strip newlines/cr's.
  1486. $prototype =~ s@^s+@@gos; # strip leading spaces
  1487. dump_function($prototype,$file);
  1488. reset_state();
  1489.     }
  1490. }
  1492. sub process_state3_type($$) { 
  1493.     my $x = shift;
  1494.     my $file = shift;
  1496.     $x =~ s@/*.*?*/@@gos; # strip comments.
  1497.     $x =~ s@[rn]+@ @gos; # strip newlines/cr's.
  1498.     $x =~ s@^s+@@gos; # strip leading spaces
  1499.     $x =~ s@s+$@@gos; # strip trailing spaces
  1501.     while (1) {
  1502.         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
  1503.     $prototype .= $1 . $2;
  1504.     ($2 eq '{') && $brcount++;
  1505.     ($2 eq '}') && $brcount--;
  1506.     if (($2 eq ';') && ($brcount == 0)) {
  1507.         dump_declaration($prototype,$file);
  1508. reset_state();
  1509.         last;
  1510.     }
  1511.     $x = $3;
  1512.         } else {
  1513.     $prototype .= $x;
  1514.     last;
  1515. }
  1516.     }
  1517. }
  1519. sub process_file($) {
  1520.     my ($file) = @_;
  1521.     my $identifier;
  1522.     my $func;
  1523.     my $initial_section_counter = $section_counter;
  1525.     if (defined($source_map{$file})) {
  1526. $file = $source_map{$file};
  1527.     }
  1529.     if (!open(IN,"<$file")) {
  1530. print STDERR "Error: Cannot open file $filen";
  1531. ++$errors;
  1532. return;
  1533.     }
  1535.     $section_counter = 0;
  1536.     while (<IN>) {
  1537. if ($state == 0) {
  1538.     if (/$doc_start/o) {
  1539. $state = 1; # next line is always the function name
  1540.     }
  1541. } elsif ($state == 1) { # this line is the function name (always)
  1542.     if (/$doc_block/o) {
  1543. $state = 4;
  1544. $contents = "";
  1545. if ( $1 eq "" ) {
  1546. $section = $section_intro;
  1547. } else {
  1548. $section = $1;
  1549. }
  1550.             }
  1551.     elsif (/$doc_decl/o) {
  1552. $identifier = $1;
  1553. if (/s*([ws]+?)s*-/) {
  1554.     $identifier = $1;
  1555. }
  1557. $state = 2;
  1558. if (/-(.*)/) {
  1559.     $declaration_purpose = $1;
  1560. } else {
  1561.     $declaration_purpose = "";
  1562. }
  1563. if ($identifier =~ m/^struct/) {
  1564.     $decl_type = 'struct';
  1565. } elsif ($identifier =~ m/^union/) {
  1566.     $decl_type = 'union';
  1567. } elsif ($identifier =~ m/^enum/) {
  1568.     $decl_type = 'enum';
  1569. } elsif ($identifier =~ m/^typedef/) {
  1570.     $decl_type = 'typedef';
  1571. } else {
  1572.     $decl_type = 'function';
  1573. }
  1575. if ($verbose) {
  1576.     print STDERR "Info(${file}:$.): Scanning doc for $identifiern";
  1577. }
  1578.     } else {
  1579. print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
  1580. " - I thought it was a doc linen";
  1581. ++$errors;
  1582. $state = 0;
  1583.     }
  1584. } elsif ($state == 2) { # look for head: lines, and include content
  1585.     if (/$doc_sect/o) {
  1586. $newsection = $1;
  1587. $newcontents = $2;
  1589. if ($contents ne "") {
  1590.     $contents =~ s/&/\\\amp;/g;
  1591.     $contents =~ s/</\\\lt;/g;
  1592.     $contents =~ s/>/\\\gt;/g;
  1593.     dump_section($section, $contents);
  1594.     $section = $section_default;
  1595. }
  1597. $contents = $newcontents;
  1598. if ($contents ne "") {
  1599.     $contents .= "n";
  1600. }
  1601. $section = $newsection;
  1602.     } elsif (/$doc_end/) {
  1604. if ($contents ne "") {
  1605.     $contents =~ s/&/\\\amp;/g;
  1606.     $contents =~ s/</\\\lt;/g;
  1607.     $contents =~ s/>/\\\gt;/g;
  1608.     dump_section($section, $contents);
  1609.     $section = $section_default;
  1610.     $contents = "";
  1611. }
  1613. $prototype = "";
  1614. $state = 3;
  1615. $brcount = 0;
  1616. #     print STDERR "end of doc comment, looking for prototypen";
  1617.     } elsif (/$doc_content/) {
  1618. # miguel-style comment kludge, look for blank lines after
  1619. # @parameter line to signify start of description
  1620. if ($1 eq "" && 
  1621. ($section =~ m/^@/ || $section eq $section_context)) {
  1622.     $contents =~ s/&/\\\amp;/g;
  1623.     $contents =~ s/</\\\lt;/g;
  1624.     $contents =~ s/>/\\\gt;/g;
  1625.     dump_section($section, $contents);
  1626.     $section = $section_default;
  1627.     $contents = "";
  1628. } else {
  1629.     $contents .= $1."n";
  1630. }
  1631.     } else {
  1632. # i dont know - bad line?  ignore.
  1633. print STDERR "Warning(${file}:$.): bad line: $_"; 
  1634. ++$errors;
  1635.     }
  1636. } elsif ($state == 3) { # scanning for function { (end of prototype)
  1637.     if ($decl_type eq 'function') {
  1638.         process_state3_function($_, $file);
  1639.     } else {
  1640.         process_state3_type($_, $file);
  1641.     }
  1642. } elsif ($state == 4) {
  1643. # Documentation block
  1644.         if (/$doc_block/) {
  1645. dump_section($section, $contents);
  1646. output_intro({'sectionlist' => @sectionlist,
  1647.       'sections' => %sections });
  1648. $contents = "";
  1649. $function = "";
  1650. %constants = ();
  1651. %parameterdescs = ();
  1652. %parametertypes = ();
  1653. @parameterlist = ();
  1654. %sections = ();
  1655. @sectionlist = ();
  1656. $prototype = "";
  1657. if ( $1 eq "" ) {
  1658. $section = $section_intro;
  1659. } else {
  1660. $section = $1;
  1661. }
  1662.                 }
  1663. elsif (/$doc_end/)
  1664. {
  1665. dump_section($section, $contents);
  1666. output_intro({'sectionlist' => @sectionlist,
  1667.       'sections' => %sections });
  1668. $contents = "";
  1669. $function = "";
  1670. %constants = ();
  1671. %parameterdescs = ();
  1672. %parametertypes = ();
  1673. @parameterlist = ();
  1674. %sections = ();
  1675. @sectionlist = ();
  1676. $prototype = "";
  1677. $state = 0;
  1678. }
  1679. elsif (/$doc_content/)
  1680. {
  1681. if ( $1 eq "" )
  1682. {
  1683. $contents .= $blankline;
  1684. }
  1685. else
  1686. {
  1687. $contents .= $1 . "n";
  1688. }
  1689.          }
  1690.           }
  1691.     }
  1692.     if ($initial_section_counter == $section_counter) {
  1693. print STDERR "Warning(${file}): no structured comments foundn";
  1694. if ($output_mode eq "sgml") {
  1695.     # The template wants at least one RefEntry here; make one.
  1696.     print "<refentry>n";
  1697.     print " <refnamediv>n";
  1698.     print "  <refname>n";
  1699.     print "   ${file}n";
  1700.     print "  </refname>n";
  1701.     print "  <refpurpose>n";
  1702.     print "   Document generation inconsistencyn";
  1703.     print "  </refpurpose>n";
  1704.     print " </refnamediv>n";
  1705.     print " <refsect1>n";
  1706.     print "  <title>n";
  1707.     print "   Oopsn";
  1708.     print "  </title>n";
  1709.     print "  <warning>n";
  1710.     print "   <para>n";
  1711.     print "    The template for this document tried to insertn";
  1712.     print "    the structured comment from the filen";
  1713.     print "    <filename>${file}</filename> at this point,n";
  1714.     print "    but none was found.n";
  1715.     print "    This dummy section is inserted to allown";
  1716.     print "    generation to continue.n";
  1717.     print "   </para>n";
  1718.     print "  </warning>n";
  1719.     print " </refsect1>n";
  1720.     print "</refentry>n";
  1721. }
  1722.     }
  1723. }