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