build/extract-doc.pl

   1 #!/usr/bin/perl
   2 # Script for extracting documentation out of header files
   3 # (c) 2008 Michal Vaner <vorner@ucw.cz>
   4
   5 use strict;
   6 use warnings;
   7
   8 my( $inname, $outname, $depname, $basedir ) = @ARGV;
   9 if( defined $inname ) {
  10         open IN, $inname or die "Could not read $inname ($!)\n";
  11 } else {
  12         open IN, "<&STDIN" or die "Could not read stdin ($!)\n";
  13 }
  14 if( defined $outname ) {
  15         open OUT, ">$outname" or die "Could not write $outname ($!)\n";
  16 } else {
  17         open OUT, ">&STDOUT" or die "Could not write to stdout ($!)\n";
  18 }
  19 my $hasdep;
  20 if( defined $depname ) {
  21         open DEP, ">>$depname" or die "Could not write $depname ($!)\n";
  22         $hasdep = 1;
  23 }
  24
  25 print DEP "$outname:" if( $hasdep );
  26
  27 sub formatNote( $$ ) {
  28         my( $head, $comment ) = @_;
  29         $head =~ s/(\S)[ ]+/$1 /g;
  30         print OUT "\n";
  31         print OUT "''''\n";
  32         chomp $head;
  33         if($head =~ /\w+\([^()]*\)/ && $head !~ /\n/) {
  34                 print OUT "!!f!$head!!!\n\n";
  35         } else {
  36                 print OUT "..................\n";
  37                 print OUT "$head\n";
  38                 print OUT "..................\n\n";
  39         }
  40         print OUT "$comment\n\n";
  41 }
  42
  43 sub process( $ ) {
  44         my $file = shift;
  45         open FILE, $file or die "Could nod read $file ($!)\n";
  46         my $line;
  47         my $active;
  48         my $verbatim;
  49         my $buff;
  50         my $head;
  51         my $struct;
  52         while( defined( $line = <FILE> ) ) {
  53                 chomp $line;
  54                 if( $struct ) {
  55                         $head .= "\n".$line;
  56                         if( $line =~ /}/ ) {
  57                                 formatNote( $head, $buff );
  58                                 $struct = 0;
  59                                 $buff = undef;
  60                                 $head = undef;
  61                         }
  62                 } elsif( $verbatim ) {
  63                         if( $line =~ /\*\// ) {
  64                                 $verbatim = 0;
  65                                 print OUT "\n";
  66                         } else {
  67                                 $line =~ s/^\s*\* ?//;
  68                                 print OUT "$line\n";
  69                         }
  70                 } elsif( $active ) {
  71                         if( $line =~ /\*\// ) {
  72                                 $active = 0;
  73                         } else {
  74                                 $line =~ s/^\s*\* ?//;
  75                                 $buff .= "$line\n";
  76                         }
  77                 } else {
  78                         if( ( $line =~ /\S/ ) && ( defined $buff ) ) {
  79                                 if( $line =~ /\(/ || $line !~ /{/ ) {
  80                                         $_ = $line;
  81                                         s/^\s*\s?//;
  82                                         s/\/\/.*//;
  83                                         s/\/\*.*?\*\///gs;
  84                                         s/[;{].*//;
  85                                         formatNote( $_, $buff );
  86                                         $head = undef;
  87                                         $buff = undef;
  88                                 } else {
  89                                         $head = $line;
  90                                         $struct = 1;
  91                                 }
  92                         } elsif( ( $buff ) = ( $line =~ /\/\*\*\*(.*)\*\*\*\// ) ) {
  93                                 $buff =~ s/\s?//;
  94                                 print OUT "$buff\n\n";
  95                                 $buff = undef;
  96                         } elsif( ( $head, $buff ) = ( $line =~ /^(.*)\/\*\*(.*)\*\*\// ) ) {
  97                                 $buff =~ s/^\s*//;
  98                                 $buff =~ s/\s*$//;
  99                                 if( $head =~ /\(/ || $head !~ /{/ ) {
 100                                         $head =~ s/^\s*//;
 101                                         $head =~ s/\/\*.*?\*\///gs;
 102                                         $head =~ s/[;{].*//;
 103                                         formatNote( $head, $buff );
 104                                         $head = undef;
 105                                         $buff = undef;
 106                                 } else {
 107                                         $struct = 1;
 108                                 }
 109                         } elsif( $line =~ /\/\*\*\*/ ) {
 110                                 $verbatim = 1;
 111                         } elsif( $line =~ /\/\*\*/ ) {
 112                                 $active = 1;
 113                         }
 114                 }
 115         }
 116         close FILE;
 117 }
 118
 119 my $line;
 120 while( defined( $line = <IN> ) ) {
 121         chomp $line;
 122         if( my( $fname ) = ( $line =~ /^!!\s*(.*\S)/ ) ) {
 123                 $fname = "$basedir/$fname" if( ( $fname !~ /^\// ) && defined $basedir );
 124                 process( $fname );
 125                 print DEP " $fname" if( $hasdep );
 126         } else {
 127                 print OUT "$line\n";
 128         }
 129 }
 130
 131 print DEP "\n" if( $hasdep );
 132
 133 close IN;
 134 close OUT;
 135 close DEP;