build/doc-extract

   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, $defdump ) = @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 $hasdump;
  20 if( defined $defdump ) {
  21         open DUMP, ">$defdump" or die "Could not write definition dump $defdump ($!)\n";
  22         $hasdump = 1;
  23 }
  24
  25 sub detect( $ ) {
  26         ( $_ ) = @_;
  27         return( $1, 1, $2, "typedef $1 { ... } $2;" ) if /^\s*typedef\s+(struct|enum)\s*{.*}\s*(\w+)\s*;\s*$/s;
  28         return( $1, 1, $2, $_ ) if /^\s*(struct|enum)\s+(\w+)\s*;\s*$/s;
  29         my $l = length;
  30         s/\n.*//s;
  31         return( $1, 0, $2, $_ ) if /(struct|enum)\s+(\w+)\s+{/;
  32         return( 'def', 0, $1, $_ ) if /#define\s+(\w+)/;
  33         if( $l > length ) {
  34                 warn( "Unknown multiline statement $_\n" );
  35                 return( '', 0, $_, $_ );
  36         }
  37         return( 'type', 1, $2, $_ ) if /^\s*typedef[^()]+?(\(\s*?\*\s*?)?(\w+)(\s*\))?\s*\(.*\)/;
  38         return( 'fun', 1, $2, $1 ) if /^(.*?(\w+)\([^{]*\)[^{]*)/;
  39         return( 'type', 1, $1, $_ ) if /^\s*typedef.*?(\w+);/;
  40         return( 'var', 1, $1, $_ ) if /\s\**(\w+);/;
  41         warn( "Unknown statement $_\n" );
  42         return( '', 0, $_, $_ );
  43 }
  44
  45 my @deps;
  46 my $id = 0;
  47
  48 sub formatNote( $$ ) {
  49         my( $head, $comment ) = @_;
  50         $head =~ s/(\S)[ ]+/$1 /g;
  51         print OUT "\n";
  52         print OUT "''''\n";
  53         chomp $head;
  54         my( $type, $semicolon, $name, $oneline ) = detect( $head );
  55         $oneline =~ s/\s+$//;
  56         $oneline =~ s/;?$/;/ if( $semicolon );
  57         $head =~ s/;?\s*$/;/ if( $semicolon );
  58         $head =~ s/(\.\.\.)/\\$1/g;
  59         print OUT "[[${type}_$name]]\n";
  60         $head = $oneline if $type eq 'fun';#Remove { from inline functions
  61         print OUT "..................\n";
  62         print OUT "$head\n";
  63         print OUT "..................\n\n";
  64         if( $hasdump ) {
  65                 print DUMP "$outname,${type}_$name,$type,$name,$oneline\n";
  66                 $id ++;
  67         }
  68         print OUT "$comment\n\n";
  69 }
  70
  71 sub process( $ ) {
  72         my $file = shift;
  73         open FILE, $file or die "Could nod read $file ($!)\n";
  74         my $line;
  75         my $active;
  76         my $verbatim;
  77         my $buff;
  78         my $head;
  79         my $struct;
  80         my $def;
  81         while( defined( $line = <FILE> ) ) {
  82                 chomp $line;
  83                 if( $def ) {
  84                         $head .= "\n".$line;
  85                         $line =~ s/(\/\*.*?\*\/|\/\/.*)//g;
  86                         if( $line !~ /\\\s*$/ ) {
  87                                 formatNote( $head, $buff );
  88                                 $def = 0;
  89                                 $buff = $head = undef;
  90                         }
  91                 } elsif( $struct ) {
  92                         $head .= "\n".$line;
  93                         if( $line =~ /}/ ) {
  94                                 formatNote( $head, $buff );
  95                                 $struct = 0;
  96                                 $buff = undef;
  97                                 $head = undef;
  98                         }
  99                 } elsif( $verbatim ) {
 100                         if( $line =~ /\*\// ) {
 101                                 $verbatim = 0;
 102                                 print OUT "\n";
 103                         } else {
 104                                 $line =~ s/^\s*\* ?//;
 105                                 print OUT "$line\n";
 106                         }
 107                 } elsif( $active ) {
 108                         if( $line =~ /\*\// ) {
 109                                 $active = 0;
 110                         } else {
 111                                 $line =~ s/^\s*\* ?//;
 112                                 $buff .= "$line\n";
 113                         }
 114                 } else {
 115                         if( ( $line =~ /\S/ ) && ( defined $buff ) ) {
 116                                 if( $line =~ /^\s*#define.*\\(\s*(\/\/.*|\/\*.*?\*\/|))*/ ) {
 117                                         $head = $line;
 118                                         $def = 1;
 119                                 } elsif( $line =~ /\(/ || $line !~ /{/ || $line =~ /^\s*#define/ ) {
 120                                         $_ = $line;
 121                                         s/^\s*\s?//;
 122                                         s/\/\/.*//;
 123                                         s/\/\*.*?\*\///gs;
 124                                         formatNote( $_, $buff );
 125                                         $head = undef;
 126                                         $buff = undef;
 127                                 } else {
 128                                         $head = $line;
 129                                         $struct = 1;
 130                                 }
 131                         } elsif( ( $buff ) = ( $line =~ /\/\*\*\*(.*)\*\*\*\// ) ) {
 132                                 $buff =~ s/\s?//;
 133                                 print OUT "$buff\n\n";
 134                                 $buff = undef;
 135                         } elsif( ( $head, $buff ) = ( $line =~ /^(.*)\/\*\*(.*)\*\*\// ) ) {
 136                                 $buff =~ s/^\s*//;
 137                                 $buff =~ s/\s*$//;
 138                                 if( $head =~ /\(/ || $head !~ /{/ || $head =~/}/ ) {
 139                                         $head =~ s/^\s*//;
 140                                         $head =~ s/\/\*.*?\*\///gs;
 141                                         formatNote( $head, $buff );
 142                                         $head = undef;
 143                                         $buff = undef;
 144                                 } else {
 145                                         $struct = 1;
 146                                 }
 147                         } elsif( $line =~ /\/\*\*\*/ ) {
 148                                 $verbatim = 1;
 149                         } elsif( $line =~ /\/\*\*/ ) {
 150                                 $active = 1;
 151                         }
 152                 }
 153         }
 154         close FILE;
 155 }
 156
 157 my $line;
 158 while( defined( $line = <IN> ) ) {
 159         chomp $line;
 160         if( my( $fname ) = ( $line =~ /^!!\s*(.*\S)/ ) ) {
 161                 $fname = "$basedir/$fname" if( ( $fname !~ /^\// ) && defined $basedir );
 162                 process( $fname );
 163                 push @deps, $fname;
 164         } else {
 165                 print OUT "$line\n";
 166         }
 167 }
 168
 169 if( defined $depname ) {
 170         open DEP, ">>$depname" or die "Could not write dep file $depname ($!)\n";
 171         print DEP "$outname:";
 172         print DEP " $_" foreach( @deps );
 173         print DEP "\n";
 174         if( $hasdump ) {
 175                 print DEP "$defdump:";
 176                 print DEP " $_" foreach( @deps );
 177                 print DEP "\n";
 178         }
 179         close DEP;
 180 }
 181
 182 close IN;
 183 close OUT;
 184 close DUMP;