projects / thirdparty / bird.git / blame
| Commit | Line | Data |
|---|---|---|
| 602b1445 PM |
1 | #!/usr/bin/perl |
| 2 | ||
| 3 | ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## | |
| 4 | ## ## | |
| 5 | ## This software falls under the GNU Public License. Please read ## | |
| 6 | ## the COPYING file for more information ## | |
| 7 | ||
| 8 | # | |
| 9 | # This will read a 'c' file and scan for embedded comments in the | |
| 10 | # style of gnome comments (+minor extensions - see below). | |
| 11 | # | |
| 12 | ||
| 13 | # Note: This only supports 'c'. | |
| 14 | ||
| 15 | # usage: | |
| c9c36117 | 16 | # kerneldoc [ -docbook | -html | -text | -man | -gnome | -bird ] |
| 602b1445 PM |
17 | # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile |
| 18 | # or | |
| 19 | # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile | |
| 20 | # | |
| c9c36117 | 21 | # Set output format using one of -docbook -html -text -man -gnome or -bird. Default is man. |
| 602b1445 PM |
22 | # |
| 23 | # -function funcname | |
| 24 | # If set, then only generate documentation for the given function(s). All | |
| 25 | # other functions are ignored. | |
| 26 | # | |
| 27 | # -nofunction funcname | |
| 28 | # If set, then only generate documentation for the other function(s). All | |
| 29 | # other functions are ignored. Cannot be used with -function together | |
| 30 | # (yes thats a bug - perl hackers can fix it 8)) | |
| 31 | # | |
| 32 | # c files - list of 'c' files to process | |
| 33 | # | |
| 34 | # All output goes to stdout, with errors to stderr. | |
| 35 | ||
| 36 | # | |
| 37 | # format of comments. | |
| 38 | # In the following table, (...)? signifies optional structure. | |
| 39 | # (...)* signifies 0 or more structure elements | |
| 40 | # /** | |
| 41 | # * function_name(:)? (- short description)? | |
| 42 | # (* @parameterx: (description of parameter x)?)* | |
| 43 | # (* a blank line)? | |
| 44 | # * (Description:)? (Description of function)? | |
| 45 | # * (section header: (section description)? )* | |
| 46 | # (*)?*/ | |
| 47 | # | |
| 48 | # So .. the trivial example would be: | |
| 49 | # | |
| 50 | # /** | |
| 51 | # * my_function | |
| 52 | # **/ | |
| 53 | # | |
| 54 | # If the Description: header tag is ommitted, then there must be a blank line | |
| 55 | # after the last parameter specification. | |
| 56 | # e.g. | |
| 57 | # /** | |
| 58 | # * my_function - does my stuff | |
| 59 | # * @my_arg: its mine damnit | |
| 60 | # * | |
| 61 | # * Does my stuff explained. | |
| 62 | # */ | |
| 63 | # | |
| 64 | # or, could also use: | |
| 65 | # /** | |
| 66 | # * my_function - does my stuff | |
| 67 | # * @my_arg: its mine damnit | |
| 68 | # * Description: Does my stuff explained. | |
| 69 | # */ | |
| 70 | # etc. | |
| 71 | # | |
| 72 | # All descriptions can be multiline, apart from the short function description. | |
| 73 | # | |
| 74 | # All descriptive text is further processed, scanning for the following special | |
| 75 | # patterns, which are highlighted appropriately. | |
| 76 | # | |
| 77 | # 'funcname()' - function | |
| 78 | # '$ENVVAR' - environmental variable | |
| b458ce83 | 79 | # '&struct_name' - name of a structure or a type |
| 602b1445 PM |
80 | # '@parameter' - name of a parameter |
| 81 | # '%CONST' - name of a constant. | |
| 2e130b5c | 82 | # '|code|' - literal string |
| 602b1445 PM |
83 | |
| 84 | # match expressions used to find embedded type information | |
| 85 | $type_constant = "\\\%(\\w+)"; | |
| 86 | $type_func = "(\\w+\\(\\))"; | |
| 87 | $type_param = "\\\@(\\w+)"; | |
| b458ce83 | 88 | $type_struct = "\\\&(\\w+)"; |
| 602b1445 | 89 | $type_env = "(\\\$\\w+)"; |
| 899fc0ab | 90 | $type_code = "\\|([^|]*)\\|"; |
| 602b1445 PM |
91 | |
| 92 | ||
| 93 | # Output conversion substitutions. | |
| 94 | # One for each output format | |
| 95 | ||
| 96 | # these work fairly well | |
| 97 | %highlights_html = ( $type_constant, "<i>\$1</i>", | |
| 98 | $type_func, "<b>\$1</b>", | |
| 99 | $type_struct, "<i>\$1</i>", | |
| 100 | $type_param, "<tt><b>\$1</b></tt>" ); | |
| 101 | $blankline_html = "<p>"; | |
| 102 | ||
| 103 | # sgml, docbook format | |
| 104 | %highlights_sgml = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>", | |
| 105 | $type_func, "<function>\$1</function>", | |
| 106 | $type_struct, "<structname>\$1</structname>", | |
| 107 | $type_env, "<envar>\$1</envar>", | |
| 108 | $type_param, "<parameter>\$1</parameter>" ); | |
| 109 | $blankline_sgml = "</para><para>\n"; | |
| 110 | ||
| 111 | # gnome, docbook format | |
| 112 | %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>", | |
| 113 | $type_func, "<function>\$1</function>", | |
| 114 | $type_struct, "<structname>\$1</structname>", | |
| 115 | $type_env, "<envar>\$1</envar>", | |
| 116 | $type_param, "<parameter>\$1</parameter>" ); | |
| 117 | $blankline_gnome = "</para><para>\n"; | |
| 118 | ||
| c9c36117 MM |
119 | # bird documentation |
| 120 | %highlights_bird = ( $type_constant, "<const/\$1/", | |
| 121 | $type_func, "<func/\$1/", | |
| 122 | $type_struct, "<struct/\$1/", | |
| 2e130b5c MM |
123 | $type_param, "<param/\$1/", |
| 124 | $type_code, "<tt>\$1</tt>"); | |
| c9c36117 MM |
125 | $blankline_bird = "<p>"; |
| 126 | ||
| 602b1445 PM |
127 | # these are pretty rough |
| 128 | %highlights_man = ( $type_constant, "\\n.I \\\"\$1\\\"\\n", | |
| 129 | $type_func, "\\n.B \\\"\$1\\\"\\n", | |
| 130 | $type_struct, "\\n.I \\\"\$1\\\"\\n", | |
| 131 | $type_param."([\.\, ]*)\n?", "\\n.I \\\"\$1\$2\\\"\\n" ); | |
| 132 | $blankline_man = ""; | |
| 133 | ||
| 134 | # text-mode | |
| 135 | %highlights_text = ( $type_constant, "\$1", | |
| 136 | $type_func, "\$1", | |
| 137 | $type_struct, "\$1", | |
| 138 | $type_param, "\$1" ); | |
| 139 | $blankline_text = ""; | |
| 140 | ||
| 141 | ||
| 142 | sub usage { | |
| 143 | print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n"; | |
| 144 | print " [ -function funcname [ -function funcname ...] ]\n"; | |
| 145 | print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; | |
| 146 | print " c source file(s) > outputfile\n"; | |
| 147 | exit 1; | |
| 148 | } | |
| 149 | ||
| 150 | # read arguments | |
| 151 | if ($#ARGV==-1) { | |
| 152 | usage(); | |
| 153 | } | |
| 154 | ||
| 155 | $verbose = 0; | |
| 156 | $output_mode = "man"; | |
| 157 | %highlights = %highlights_man; | |
| 158 | $blankline = $blankline_man; | |
| 159 | $modulename = "API Documentation"; | |
| 160 | $function_only = 0; | |
| 161 | while ($ARGV[0] =~ m/^-(.*)/) { | |
| 162 | $cmd = shift @ARGV; | |
| 163 | if ($cmd eq "-html") { | |
| 164 | $output_mode = "html"; | |
| 165 | %highlights = %highlights_html; | |
| 166 | $blankline = $blankline_html; | |
| 167 | } elsif ($cmd eq "-man") { | |
| 168 | $output_mode = "man"; | |
| 169 | %highlights = %highlights_man; | |
| 170 | $blankline = $blankline_man; | |
| 171 | } elsif ($cmd eq "-text") { | |
| 172 | $output_mode = "text"; | |
| 173 | %highlights = %highlights_text; | |
| 174 | $blankline = $blankline_text; | |
| 175 | } elsif ($cmd eq "-docbook") { | |
| 176 | $output_mode = "sgml"; | |
| 177 | %highlights = %highlights_sgml; | |
| 178 | $blankline = $blankline_sgml; | |
| 179 | } elsif ($cmd eq "-gnome") { | |
| 180 | $output_mode = "gnome"; | |
| 181 | %highlights = %highlights_gnome; | |
| 182 | $blankline = $blankline_gnome; | |
| c9c36117 MM |
183 | } elsif ($cmd eq "-bird") { |
| 184 | $output_mode = "bird"; | |
| 185 | %highlights = %highlights_bird; | |
| 186 | $blankline = $blankline_bird; | |
| 602b1445 PM |
187 | } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document |
| 188 | $modulename = shift @ARGV; | |
| 189 | } elsif ($cmd eq "-function") { # to only output specific functions | |
| 190 | $function_only = 1; | |
| 191 | $function = shift @ARGV; | |
| 192 | $function_table{$function} = 1; | |
| 193 | } elsif ($cmd eq "-nofunction") { # to only output specific functions | |
| 194 | $function_only = 2; | |
| 195 | $function = shift @ARGV; | |
| 196 | $function_table{$function} = 1; | |
| 197 | } elsif ($cmd eq "-v") { | |
| 198 | $verbose = 1; | |
| 199 | } elsif (($cmd eq "-h") || ($cmd eq "--help")) { | |
| 200 | usage(); | |
| 201 | } | |
| 202 | } | |
| 203 | ||
| 204 | ||
| 205 | # generate a sequence of code that will splice in highlighting information | |
| 206 | # using the s// operator. | |
| 207 | $dohighlight = ""; | |
| 208 | foreach $pattern (keys %highlights) { | |
| 209 | # print "scanning pattern $pattern ($highlights{$pattern})\n"; | |
| 210 | $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; | |
| 211 | } | |
| 212 | ||
| 213 | ## | |
| 214 | # dumps section contents to arrays/hashes intended for that purpose. | |
| 215 | # | |
| 216 | sub dump_section { | |
| 217 | my $name = shift @_; | |
| 218 | my $contents = join "\n", @_; | |
| 219 | ||
| 220 | if ($name =~ m/$type_constant/) { | |
| 221 | $name = $1; | |
| 222 | # print STDERR "constant section '$1' = '$contents'\n"; | |
| 223 | $constants{$name} = $contents; | |
| 224 | } elsif ($name =~ m/$type_param/) { | |
| 225 | # print STDERR "parameter def '$1' = '$contents'\n"; | |
| 226 | $name = $1; | |
| 227 | $parameters{$name} = $contents; | |
| 228 | } else { | |
| 229 | # print STDERR "other section '$name' = '$contents'\n"; | |
| 230 | $sections{$name} = $contents; | |
| 231 | push @sectionlist, $name; | |
| 232 | } | |
| 233 | } | |
| 234 | ||
| 235 | ## | |
| 236 | # output function | |
| 237 | # | |
| 238 | # parameters, a hash. | |
| 239 | # function => "function name" | |
| 240 | # parameterlist => @list of parameters | |
| 241 | # parameters => %parameter descriptions | |
| 242 | # sectionlist => @list of sections | |
| 243 | # sections => %descriont descriptions | |
| 244 | # | |
| 245 | ||
| 246 | sub output_highlight { | |
| 247 | my $contents = join "\n", @_; | |
| 248 | my $line; | |
| 249 | ||
| 250 | eval $dohighlight; | |
| 251 | foreach $line (split "\n", $contents) { | |
| 252 | if ($line eq ""){ | |
| 253 | print $lineprefix, $blankline; | |
| 254 | } else { | |
| 255 | $line =~ s/\\\\\\/\&/g; | |
| 256 | print $lineprefix, $line; | |
| 257 | } | |
| 258 | print "\n"; | |
| 259 | } | |
| 260 | } | |
| 261 | ||
| 262 | ||
| 263 | # output in html | |
| 264 | sub output_html { | |
| 265 | my %args = %{$_[0]}; | |
| 266 | my ($parameter, $section); | |
| 267 | my $count; | |
| 268 | print "<h2>Function</h2>\n"; | |
| 269 | ||
| 270 | print "<i>".$args{'functiontype'}."</i>\n"; | |
| 271 | print "<b>".$args{'function'}."</b>\n"; | |
| 272 | print "("; | |
| 273 | $count = 0; | |
| 274 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 275 | print "<i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n"; | |
| 276 | if ($count != $#{$args{'parameterlist'}}) { | |
| 277 | $count++; | |
| 278 | print ", "; | |
| 279 | } | |
| 280 | } | |
| 281 | print ")\n"; | |
| 282 | ||
| 283 | print "<h3>Arguments</h3>\n"; | |
| 284 | print "<dl>\n"; | |
| 285 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 286 | print "<dt><i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n"; | |
| 287 | print "<dd>"; | |
| 288 | output_highlight($args{'parameters'}{$parameter}); | |
| 289 | } | |
| 290 | print "</dl>\n"; | |
| 291 | foreach $section (@{$args{'sectionlist'}}) { | |
| 2337ade7 | 292 | print "<h1>$section</h1>\n"; |
| 602b1445 PM |
293 | print "<ul>\n"; |
| 294 | output_highlight($args{'sections'}{$section}); | |
| 295 | print "</ul>\n"; | |
| 296 | } | |
| 297 | print "<hr>\n"; | |
| 298 | } | |
| 299 | ||
| 300 | ||
| 301 | # output in html | |
| 302 | sub output_intro_html { | |
| 303 | my %args = %{$_[0]}; | |
| 304 | my ($parameter, $section); | |
| 305 | my $count; | |
| 306 | ||
| 307 | foreach $section (@{$args{'sectionlist'}}) { | |
| 2337ade7 | 308 | print "<h1>$section</h1>\n"; |
| 602b1445 PM |
309 | print "<ul>\n"; |
| 310 | output_highlight($args{'sections'}{$section}); | |
| 311 | print "</ul>\n"; | |
| 312 | } | |
| 313 | print "<hr>\n"; | |
| 314 | } | |
| 315 | ||
| 316 | ||
| 317 | ||
| 318 | # output in sgml DocBook | |
| 319 | sub output_sgml { | |
| 320 | my %args = %{$_[0]}; | |
| 321 | my ($parameter, $section); | |
| 322 | my $count; | |
| 323 | my $id; | |
| 324 | ||
| 325 | $id = $args{'module'}."-".$args{'function'}; | |
| 326 | $id =~ s/[^A-Za-z0-9]/-/g; | |
| 327 | ||
| 328 | print "<refentry>\n"; | |
| 329 | print "<refmeta>\n"; | |
| 330 | print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n"; | |
| 331 | print "</refmeta>\n"; | |
| 332 | print "<refnamediv>\n"; | |
| 333 | print " <refname>".$args{'function'}."</refname>\n"; | |
| 334 | print " <refpurpose>\n"; | |
| 335 | print " ".$args{'purpose'}."\n"; | |
| 336 | print " </refpurpose>\n"; | |
| 337 | print "</refnamediv>\n"; | |
| 338 | ||
| 339 | print "<refsynopsisdiv>\n"; | |
| 340 | print " <title>Synopsis</title>\n"; | |
| 341 | print " <funcsynopsis>\n"; | |
| 342 | print " <funcdef>".$args{'functiontype'}." "; | |
| 343 | print "<function>".$args{'function'}." "; | |
| 344 | print "</function></funcdef>\n"; | |
| 345 | ||
| 346 | # print "<refsect1>\n"; | |
| 347 | # print " <title>Synopsis</title>\n"; | |
| 348 | # print " <funcsynopsis>\n"; | |
| 349 | # print " <funcdef>".$args{'functiontype'}." "; | |
| 350 | # print "<function>".$args{'function'}." "; | |
| 351 | # print "</function></funcdef>\n"; | |
| 352 | ||
| 353 | $count = 0; | |
| 354 | if ($#{$args{'parameterlist'}} >= 0) { | |
| 355 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 356 | print " <paramdef>".$args{'parametertypes'}{$parameter}; | |
| 357 | print " <parameter>$parameter</parameter></paramdef>\n"; | |
| 358 | } | |
| 359 | } else { | |
| 360 | print " <void>\n"; | |
| 361 | } | |
| 362 | print " </funcsynopsis>\n"; | |
| 363 | print "</refsynopsisdiv>\n"; | |
| 364 | # print "</refsect1>\n"; | |
| 365 | ||
| 366 | # print parameters | |
| 367 | print "<refsect1>\n <title>Arguments</title>\n"; | |
| 368 | # print "<para>\nArguments\n"; | |
| 369 | if ($#{$args{'parameterlist'}} >= 0) { | |
| 370 | print " <variablelist>\n"; | |
| 371 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 372 | print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n"; | |
| 373 | print " <listitem>\n <para>\n"; | |
| 374 | $lineprefix=" "; | |
| 375 | output_highlight($args{'parameters'}{$parameter}); | |
| 376 | print " </para>\n </listitem>\n </varlistentry>\n"; | |
| 377 | } | |
| 378 | print " </variablelist>\n"; | |
| 379 | } else { | |
| 380 | print " <para>\n None\n </para>\n"; | |
| 381 | } | |
| 382 | print "</refsect1>\n"; | |
| 383 | ||
| 384 | # print out each section | |
| 385 | $lineprefix=" "; | |
| 386 | foreach $section (@{$args{'sectionlist'}}) { | |
| 387 | print "<refsect1>\n <title>$section</title>\n <para>\n"; | |
| 388 | # print "<para>\n$section\n"; | |
| 389 | if ($section =~ m/EXAMPLE/i) { | |
| 390 | print "<example><para>\n"; | |
| 391 | } | |
| 392 | output_highlight($args{'sections'}{$section}); | |
| 393 | # print "</para>"; | |
| 394 | if ($section =~ m/EXAMPLE/i) { | |
| 395 | print "</para></example>\n"; | |
| 396 | } | |
| 397 | print " </para>\n</refsect1>\n"; | |
| 398 | } | |
| 399 | ||
| 400 | print "</refentry>\n\n"; | |
| 401 | } | |
| 402 | ||
| 403 | # output in sgml DocBook | |
| 404 | sub output_intro_sgml { | |
| 405 | my %args = %{$_[0]}; | |
| 406 | my ($parameter, $section); | |
| 407 | my $count; | |
| 408 | my $id; | |
| 409 | ||
| 410 | $id = $args{'module'}; | |
| 411 | $id =~ s/[^A-Za-z0-9]/-/g; | |
| 412 | ||
| 413 | # print out each section | |
| 414 | $lineprefix=" "; | |
| 415 | foreach $section (@{$args{'sectionlist'}}) { | |
| 416 | print "<refsect1>\n <title>$section</title>\n <para>\n"; | |
| 417 | # print "<para>\n$section\n"; | |
| 418 | if ($section =~ m/EXAMPLE/i) { | |
| 419 | print "<example><para>\n"; | |
| 420 | } | |
| 421 | output_highlight($args{'sections'}{$section}); | |
| 422 | # print "</para>"; | |
| 423 | if ($section =~ m/EXAMPLE/i) { | |
| 424 | print "</para></example>\n"; | |
| 425 | } | |
| 426 | print " </para>\n</refsect1>\n"; | |
| 427 | } | |
| 428 | ||
| 429 | print "\n\n"; | |
| 430 | } | |
| 431 | ||
| 432 | # output in sgml DocBook | |
| 433 | sub output_gnome { | |
| 434 | my %args = %{$_[0]}; | |
| 435 | my ($parameter, $section); | |
| 436 | my $count; | |
| 437 | my $id; | |
| 438 | ||
| 439 | $id = $args{'module'}."-".$args{'function'}; | |
| 440 | $id =~ s/[^A-Za-z0-9]/-/g; | |
| 441 | ||
| 442 | print "<sect2>\n"; | |
| 443 | print " <title id=\"$id\">".$args{'function'}."</title>\n"; | |
| 444 | ||
| 445 | # print "<simplesect>\n"; | |
| 446 | # print " <title>Synopsis</title>\n"; | |
| 447 | print " <funcsynopsis>\n"; | |
| 448 | print " <funcdef>".$args{'functiontype'}." "; | |
| 449 | print "<function>".$args{'function'}." "; | |
| 450 | print "</function></funcdef>\n"; | |
| 451 | ||
| 452 | $count = 0; | |
| 453 | if ($#{$args{'parameterlist'}} >= 0) { | |
| 454 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 455 | print " <paramdef>".$args{'parametertypes'}{$parameter}; | |
| 456 | print " <parameter>$parameter</parameter></paramdef>\n"; | |
| 457 | } | |
| 458 | } else { | |
| 459 | print " <void>\n"; | |
| 460 | } | |
| 461 | print " </funcsynopsis>\n"; | |
| 462 | # print "</simplesect>\n"; | |
| 463 | # print "</refsect1>\n"; | |
| 464 | ||
| 465 | # print parameters | |
| 466 | # print "<simplesect>\n <title>Arguments</title>\n"; | |
| 467 | # if ($#{$args{'parameterlist'}} >= 0) { | |
| 468 | # print " <variablelist>\n"; | |
| 469 | # foreach $parameter (@{$args{'parameterlist'}}) { | |
| 470 | # print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n"; | |
| 471 | # print " <listitem>\n <para>\n"; | |
| 472 | # $lineprefix=" "; | |
| 473 | # output_highlight($args{'parameters'}{$parameter}); | |
| 474 | # print " </para>\n </listitem>\n </varlistentry>\n"; | |
| 475 | # } | |
| 476 | # print " </variablelist>\n"; | |
| 477 | # } else { | |
| 478 | # print " <para>\n None\n </para>\n"; | |
| 479 | # } | |
| 480 | # print "</simplesect>\n"; | |
| 481 | ||
| 482 | # print "<simplesect>\n <title>Arguments</title>\n"; | |
| 483 | if ($#{$args{'parameterlist'}} >= 0) { | |
| 484 | print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n"; | |
| 485 | print "<tgroup cols=\"2\">\n"; | |
| 486 | print "<colspec colwidth=\"2*\">\n"; | |
| 487 | print "<colspec colwidth=\"8*\">\n"; | |
| 488 | print "<tbody>\n"; | |
| 489 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 490 | print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n"; | |
| 491 | print " <entry>\n"; | |
| 492 | $lineprefix=" "; | |
| 493 | output_highlight($args{'parameters'}{$parameter}); | |
| 494 | print " </entry></row>\n"; | |
| 495 | } | |
| 496 | print " </tbody></tgroup></informaltable>\n"; | |
| 497 | } else { | |
| 498 | print " <para>\n None\n </para>\n"; | |
| 499 | } | |
| 500 | # print "</simplesect>\n"; | |
| 501 | ||
| 502 | # print out each section | |
| 503 | $lineprefix=" "; | |
| 504 | foreach $section (@{$args{'sectionlist'}}) { | |
| 505 | print "<simplesect>\n <title>$section</title>\n"; | |
| 506 | # print "<para>\n$section\n"; | |
| 507 | if ($section =~ m/EXAMPLE/i) { | |
| 508 | print "<example><programlisting>\n"; | |
| 509 | } else { | |
| 510 | } | |
| 511 | print "<para>\n"; | |
| 512 | output_highlight($args{'sections'}{$section}); | |
| 513 | # print "</para>"; | |
| 514 | print "</para>\n"; | |
| 515 | if ($section =~ m/EXAMPLE/i) { | |
| 516 | print "</programlisting></example>\n"; | |
| 517 | } else { | |
| 518 | } | |
| 519 | print " </simplesect>\n"; | |
| 520 | } | |
| 521 | ||
| 522 | print "</sect2>\n\n"; | |
| 523 | } | |
| 524 | ||
| c9c36117 MM |
525 | # output in birddoc |
| 526 | sub output_bird { | |
| 527 | my %args = %{$_[0]}; | |
| 528 | my ($parameter, $section); | |
| 529 | my $count; | |
| fcdddff5 | 530 | print "<function><p><type>".$args{'functiontype'}."</type>\n"; |
| c9c36117 MM |
531 | print "<funcdef>".$args{'function'}."</funcdef>\n"; |
| 532 | print "("; | |
| 533 | $count = 0; | |
| 658d272b | 534 | my $ntyped = 0; |
| c9c36117 | 535 | foreach $parameter (@{$args{'parameterlist'}}) { |
| 658d272b MM |
536 | if ($args{'parametertypes'}{$parameter} ne "") { |
| 537 | print "<type>".$args{'parametertypes'}{$parameter}."</type> "; | |
| 538 | $ntyped++; | |
| 539 | } | |
| 540 | print "<param>".$parameter."</param>"; | |
| c9c36117 MM |
541 | if ($count != $#{$args{'parameterlist'}}) { |
| 542 | $count++; | |
| 543 | print ", "; | |
| 544 | } | |
| 545 | } | |
| b458ce83 | 546 | print ")"; |
| 854128a5 | 547 | if ($args{'purpose'} ne "") { |
| b458ce83 MM |
548 | print " -- "; |
| 549 | output_highlight($args{'purpose'}); | |
| 550 | } | |
| 551 | print "\n"; | |
| c9c36117 | 552 | |
| 658d272b MM |
553 | if ($ntyped) { |
| 554 | print "<funcsect>Arguments\n"; | |
| 555 | print "<p><descrip>\n"; | |
| 556 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 557 | print "<tagp><type>".$args{'parametertypes'}{$parameter}."</type> <param>".$parameter."</param></tagp>\n"; | |
| 558 | output_highlight($args{'parameters'}{$parameter}); | |
| 559 | } | |
| 560 | print "</descrip>\n"; | |
| c9c36117 | 561 | } |
| c9c36117 | 562 | foreach $section (@{$args{'sectionlist'}}) { |
| c23f40b1 | 563 | print "<funcsect>$section\n"; |
| c9c36117 MM |
564 | print "<p>\n"; |
| 565 | output_highlight($args{'sections'}{$section}); | |
| 566 | } | |
| fcdddff5 | 567 | print "</function>\n"; |
| c9c36117 MM |
568 | } |
| 569 | ||
| 570 | # output in birddoc | |
| 571 | sub output_intro_bird { | |
| 572 | my %args = %{$_[0]}; | |
| 573 | my ($parameter, $section); | |
| 574 | my $count; | |
| 575 | my $id; | |
| 576 | ||
| 577 | $id = $args{'module'}; | |
| 578 | $id =~ s/[^A-Za-z0-9]/-/g; | |
| 579 | ||
| 580 | # print out each section | |
| 581 | $lineprefix=" "; | |
| 582 | foreach $section (@{$args{'sectionlist'}}) { | |
| 371adba6 | 583 | print "<sect>$section\n<p>\n"; |
| c9c36117 MM |
584 | output_highlight($args{'sections'}{$section}); |
| 585 | } | |
| 586 | ||
| 587 | print "\n\n"; | |
| 588 | } | |
| 589 | ||
| 602b1445 PM |
590 | ## |
| 591 | # output in man | |
| 592 | sub output_man { | |
| 593 | my %args = %{$_[0]}; | |
| 594 | my ($parameter, $section); | |
| 595 | my $count; | |
| 596 | ||
| 597 | print ".TH \"$args{'module'}\" \"$args{'function'}\" \"25 May 1998\" \"API Manual\" LINUX\n"; | |
| 598 | ||
| 599 | print ".SH Function\n"; | |
| 600 | ||
| 601 | print ".I \"".$args{'functiontype'}."\"\n"; | |
| 602 | print ".B \"".$args{'function'}."\"\n"; | |
| 603 | print "(\n"; | |
| 604 | $count = 0; | |
| 605 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 606 | print ".I \"".$args{'parametertypes'}{$parameter}."\"\n.B \"".$parameter."\"\n"; | |
| 607 | if ($count != $#{$args{'parameterlist'}}) { | |
| 608 | $count++; | |
| 609 | print ",\n"; | |
| 610 | } | |
| 611 | } | |
| 612 | print ")\n"; | |
| 613 | ||
| 614 | print ".SH Arguments\n"; | |
| 615 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 616 | print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n"; | |
| 617 | output_highlight($args{'parameters'}{$parameter}); | |
| 618 | } | |
| 619 | foreach $section (@{$args{'sectionlist'}}) { | |
| 620 | print ".SH \"$section\"\n"; | |
| 621 | output_highlight($args{'sections'}{$section}); | |
| 622 | } | |
| 623 | } | |
| 624 | ||
| 625 | sub output_intro_man { | |
| 626 | my %args = %{$_[0]}; | |
| 627 | my ($parameter, $section); | |
| 628 | my $count; | |
| 629 | ||
| 630 | print ".TH \"$args{'module'}\" \"$args{'module'}\" \"25 May 1998\" \"API Manual\" LINUX\n"; | |
| 631 | ||
| 632 | foreach $section (@{$args{'sectionlist'}}) { | |
| 633 | print ".SH \"$section\"\n"; | |
| 634 | output_highlight($args{'sections'}{$section}); | |
| 635 | } | |
| 636 | } | |
| 637 | ||
| 638 | ## | |
| 639 | # output in text | |
| 640 | sub output_text { | |
| 641 | my %args = %{$_[0]}; | |
| 642 | my ($parameter, $section); | |
| 643 | ||
| 644 | print "Function = ".$args{'function'}."\n"; | |
| 645 | print " return type: ".$args{'functiontype'}."\n\n"; | |
| 646 | foreach $parameter (@{$args{'parameterlist'}}) { | |
| 647 | print " ".$args{'parametertypes'}{$parameter}." ".$parameter."\n"; | |
| 648 | print " -> ".$args{'parameters'}{$parameter}."\n"; | |
| 649 | } | |
| 650 | foreach $section (@{$args{'sectionlist'}}) { | |
| 651 | print " $section:\n"; | |
| 652 | print " -> "; | |
| 653 | output_highlight($args{'sections'}{$section}); | |
| 654 | } | |
| 655 | } | |
| 656 | ||
| 657 | sub output_intro_text { | |
| 658 | my %args = %{$_[0]}; | |
| 659 | my ($parameter, $section); | |
| 660 | ||
| 661 | foreach $section (@{$args{'sectionlist'}}) { | |
| 662 | print " $section:\n"; | |
| 663 | print " -> "; | |
| 664 | output_highlight($args{'sections'}{$section}); | |
| 665 | } | |
| 666 | } | |
| 667 | ||
| 668 | ## | |
| 669 | # generic output function - calls the right one based | |
| 670 | # on current output mode. | |
| 671 | sub output_function { | |
| 672 | # output_html(@_); | |
| 673 | eval "output_".$output_mode."(\@_);"; | |
| 674 | } | |
| 675 | ||
| 676 | ## | |
| 677 | # generic output function - calls the right one based | |
| 678 | # on current output mode. | |
| 679 | sub output_intro { | |
| 680 | # output_html(@_); | |
| 681 | eval "output_intro_".$output_mode."(\@_);"; | |
| 682 | } | |
| 683 | ||
| 684 | ||
| 685 | ## | |
| 686 | # takes a function prototype and spits out all the details | |
| 687 | # stored in the global arrays/hsahes. | |
| 688 | sub dump_function { | |
| 689 | my $prototype = shift @_; | |
| 690 | ||
| 691 | $prototype =~ s/^static+ //; | |
| 692 | $prototype =~ s/^extern+ //; | |
| 693 | $prototype =~ s/^inline+ //; | |
| 694 | $prototype =~ s/^__inline__+ //; | |
| 695 | ||
| 696 | if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ || | |
| 697 | $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ || | |
| 698 | $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ || | |
| 699 | $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ || | |
| 700 | $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/) { | |
| 701 | $return_type = $1; | |
| 702 | $function_name = $2; | |
| 703 | $args = $3; | |
| 704 | ||
| 705 | # print STDERR "ARGS = '$args'\n"; | |
| 706 | ||
| 707 | foreach $arg (split ',', $args) { | |
| 708 | # strip leading/trailing spaces | |
| 709 | $arg =~ s/^\s*//; | |
| 710 | $arg =~ s/\s*$//; | |
| 711 | # print STDERR "SCAN ARG: '$arg'\n"; | |
| 712 | @args = split('\s', $arg); | |
| 713 | ||
| 714 | # print STDERR " -> @args\n"; | |
| 715 | $param = pop @args; | |
| 716 | # print STDERR " -> @args\n"; | |
| 717 | if ($param =~ m/^(\*+)(.*)/) { | |
| 718 | $param = $2; | |
| 719 | push @args, $1; | |
| 720 | } | |
| 721 | $type = join " ", @args; | |
| 722 | ||
| 723 | if ($type eq "" && $param eq "...") | |
| 724 | { | |
| 725 | $type="..."; | |
| 726 | $param="..."; | |
| 727 | $parameters{"..."} = "variable arguments"; | |
| 728 | } | |
| 729 | if ($type eq "") | |
| 730 | { | |
| 731 | $type=""; | |
| 732 | $param="void"; | |
| 733 | $parameters{void} = "no arguments"; | |
| 734 | } | |
| 735 | if ($parameters{$param} eq "") { | |
| 736 | $parameters{$param} = "-- undescribed --"; | |
| 737 | print STDERR "Warning($lineno): Function parameter '$param' not described in '$function_name'\n"; | |
| 738 | } | |
| 739 | ||
| 740 | push @parameterlist, $param; | |
| 741 | $parametertypes{$param} = $type; | |
| 742 | # print STDERR "param = '$param', type = '$type'\n"; | |
| 743 | } | |
| 744 | } else { | |
| 745 | print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n"; | |
| 746 | return; | |
| 747 | } | |
| 748 | ||
| 749 | if ($function_only==0 || | |
| 750 | ( $function_only == 1 && defined($function_table{$function_name})) || | |
| 751 | ( $function_only == 2 && !defined($function_table{$function_name}))) | |
| 752 | { | |
| 753 | output_function({'function' => $function_name, | |
| 754 | 'module' => $modulename, | |
| 755 | 'functiontype' => $return_type, | |
| 756 | 'parameterlist' => \@parameterlist, | |
| 757 | 'parameters' => \%parameters, | |
| 758 | 'parametertypes' => \%parametertypes, | |
| 759 | 'sectionlist' => \@sectionlist, | |
| 760 | 'sections' => \%sections, | |
| 761 | 'purpose' => $function_purpose | |
| 762 | }); | |
| 763 | } | |
| 764 | } | |
| 765 | ||
| 766 | ###################################################################### | |
| 767 | # main | |
| 768 | # states | |
| 769 | # 0 - normal code | |
| 770 | # 1 - looking for function name | |
| 771 | # 2 - scanning field start. | |
| 772 | # 3 - scanning prototype. | |
| 773 | $state = 0; | |
| 774 | $section = ""; | |
| 775 | ||
| 776 | $doc_special = "\@\%\$\&"; | |
| 777 | ||
| 778 | $doc_start = "^/\\*\\*\$"; | |
| 779 | $doc_end = "\\*/"; | |
| 780 | $doc_com = "\\s*\\*\\s*"; | |
| 781 | $doc_func = $doc_com."(\\w+):?"; | |
| 782 | $doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)"; | |
| 783 | $doc_content = $doc_com."(.*)"; | |
| 784 | $doc_block = $doc_com."DOC:\\s*(.*)?"; | |
| 785 | ||
| 786 | %constants = (); | |
| 787 | %parameters = (); | |
| 788 | @parameterlist = (); | |
| 789 | %sections = (); | |
| 790 | @sectionlist = (); | |
| 791 | ||
| 792 | $contents = ""; | |
| 793 | $section_default = "Description"; # default section | |
| 794 | $section_intro = "Introduction"; | |
| 795 | $section = $section_default; | |
| 796 | ||
| 797 | $lineno = 0; | |
| 798 | foreach $file (@ARGV) { | |
| 799 | if (!open(IN,"<$file")) { | |
| 800 | print STDERR "Error: Cannot open file $file\n"; | |
| 801 | next; | |
| 802 | } | |
| 803 | while (<IN>) { | |
| 804 | $lineno++; | |
| 805 | ||
| 806 | if ($state == 0) { | |
| 807 | if (/$doc_start/o) { | |
| 808 | $state = 1; # next line is always the function name | |
| 809 | } | |
| 810 | } elsif ($state == 1) { # this line is the function name (always) | |
| 811 | if (/$doc_block/o) { | |
| 812 | $state = 4; | |
| 813 | $contents = ""; | |
| 814 | if ( $1 eq "" ) { | |
| 815 | $section = $section_intro; | |
| 816 | } else { | |
| 817 | $section = $1; | |
| 818 | } | |
| 819 | } | |
| 820 | elsif (/$doc_func/o) { | |
| 821 | $function = $1; | |
| 822 | $state = 2; | |
| 823 | if (/-(.*)/) { | |
| 824 | $function_purpose = $1; | |
| 825 | } else { | |
| 826 | $function_purpose = ""; | |
| 827 | } | |
| 828 | if ($verbose) { | |
| 829 | print STDERR "Info($lineno): Scanning doc for $function\n"; | |
| 830 | } | |
| 831 | } else { | |
| 832 | print STDERR "WARN($lineno): Cannot understand $_ on line $lineno", | |
| 833 | " - I thought it was a doc line\n"; | |
| 834 | $state = 0; | |
| 835 | } | |
| 836 | } elsif ($state == 2) { # look for head: lines, and include content | |
| 837 | if (/$doc_sect/o) { | |
| 838 | $newsection = $1; | |
| 839 | $newcontents = $2; | |
| 840 | ||
| 841 | if ($contents ne "") { | |
| b458ce83 | 842 | # $contents =~ s/\&/\\\\\\amp;/g; |
| 602b1445 PM |
843 | $contents =~ s/\</\\\\\\lt;/g; |
| 844 | $contents =~ s/\>/\\\\\\gt;/g; | |
| 845 | dump_section($section, $contents); | |
| 846 | $section = $section_default; | |
| 847 | } | |
| 848 | ||
| 849 | $contents = $newcontents; | |
| 850 | if ($contents ne "") { | |
| 851 | $contents .= "\n"; | |
| 852 | } | |
| 853 | $section = $newsection; | |
| 854 | } elsif (/$doc_end/) { | |
| 855 | ||
| 856 | if ($contents ne "") { | |
| b458ce83 | 857 | # $contents =~ s/\&/\\\\\\amp;/g; |
| 602b1445 PM |
858 | $contents =~ s/\</\\\\\\lt;/g; |
| 859 | $contents =~ s/\>/\\\\\\gt;/g; | |
| 860 | dump_section($section, $contents); | |
| 861 | $section = $section_default; | |
| 862 | $contents = ""; | |
| 863 | } | |
| 864 | ||
| 865 | # print STDERR "end of doc comment, looking for prototype\n"; | |
| 866 | $prototype = ""; | |
| 867 | $state = 3; | |
| 868 | } elsif (/$doc_content/) { | |
| 869 | # miguel-style comment kludge, look for blank lines after | |
| 870 | # @parameter line to signify start of description | |
| 871 | if ($1 eq "" && $section =~ m/^@/) { | |
| b458ce83 | 872 | # $contents =~ s/\&/\\\\\\amp;/g; |
| 602b1445 PM |
873 | $contents =~ s/\</\\\\\\lt;/g; |
| 874 | $contents =~ s/\>/\\\\\\gt;/g; | |
| 875 | dump_section($section, $contents); | |
| 876 | $section = $section_default; | |
| 877 | $contents = ""; | |
| 878 | } else { | |
| 879 | $contents .= $1."\n"; | |
| 880 | } | |
| 881 | } else { | |
| 882 | # i dont know - bad line? ignore. | |
| 883 | print STDERR "WARNING($lineno): bad line: $_"; | |
| 884 | } | |
| 885 | } elsif ($state == 3) { # scanning for function { (end of prototype) | |
| 886 | if (m#\s*/\*\s+MACDOC\s*#io) { | |
| 887 | # do nothing | |
| 888 | } | |
| 889 | elsif (/([^\{]*)/) { | |
| 890 | $prototype .= $1; | |
| 891 | } | |
| 892 | if (/\{/) { | |
| 893 | $prototype =~ s@/\*.*?\*/@@gos; # strip comments. | |
| 894 | $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. | |
| 895 | $prototype =~ s@^ +@@gos; # strip leading spaces | |
| 896 | dump_function($prototype); | |
| 897 | ||
| 898 | $function = ""; | |
| 899 | %constants = (); | |
| 900 | %parameters = (); | |
| 901 | %parametertypes = (); | |
| 902 | @parameterlist = (); | |
| 903 | %sections = (); | |
| 904 | @sectionlist = (); | |
| 905 | $prototype = ""; | |
| 906 | ||
| 907 | $state = 0; | |
| 908 | } | |
| 909 | } elsif ($state == 4) { | |
| 910 | # Documentation block | |
| 911 | if (/$doc_block/) { | |
| b458ce83 | 912 | # $contents =~ s/\&/\\\\\\amp;/g; |
| 7e602d5e MM |
913 | $contents =~ s/\</\\\\\\lt;/g; |
| 914 | $contents =~ s/\>/\\\\\\gt;/g; | |
| 602b1445 PM |
915 | dump_section($section, $contents); |
| 916 | output_intro({'sectionlist' => \@sectionlist, | |
| 917 | 'sections' => \%sections }); | |
| 918 | $contents = ""; | |
| 919 | $function = ""; | |
| 920 | %constants = (); | |
| 921 | %parameters = (); | |
| 922 | %parametertypes = (); | |
| 923 | @parameterlist = (); | |
| 924 | %sections = (); | |
| 925 | @sectionlist = (); | |
| 926 | $prototype = ""; | |
| 927 | if ( $1 eq "" ) { | |
| 928 | $section = $section_intro; | |
| 929 | } else { | |
| 930 | $section = $1; | |
| 931 | } | |
| 932 | } | |
| 933 | elsif (/$doc_end/) | |
| 934 | { | |
| b458ce83 | 935 | # $contents =~ s/\&/\\\\\\amp;/g; |
| 7e602d5e MM |
936 | $contents =~ s/\</\\\\\\lt;/g; |
| 937 | $contents =~ s/\>/\\\\\\gt;/g; | |
| 602b1445 PM |
938 | dump_section($section, $contents); |
| 939 | output_intro({'sectionlist' => \@sectionlist, | |
| 940 | 'sections' => \%sections }); | |
| 941 | $contents = ""; | |
| 942 | $function = ""; | |
| 943 | %constants = (); | |
| 944 | %parameters = (); | |
| 945 | %parametertypes = (); | |
| 946 | @parameterlist = (); | |
| 947 | %sections = (); | |
| 948 | @sectionlist = (); | |
| 949 | $prototype = ""; | |
| 950 | $state = 0; | |
| 951 | } | |
| 952 | elsif (/$doc_content/) | |
| 953 | { | |
| 954 | if ( $1 eq "" ) | |
| 955 | { | |
| 7e602d5e | 956 | $contents .= "\n"; |
| 602b1445 PM |
957 | } |
| 958 | else | |
| 959 | { | |
| 960 | $contents .= $1 . "\n"; | |
| 961 | } | |
| 962 | } | |
| 963 | } | |
| 964 | } | |
| 965 | } | |
| 966 |