kernel-doc 52 KB

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