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 my @deps;
  26 my $id = 0;
  27
  28 sub formatNote( $$ ) {
  29         my( $head, $comment ) = @_;
  30         $head =~ s/(\S)[ ]+/$1 /g;
  31         print OUT "\n";
  32         print OUT "''''\n";
  33         chomp $head;
  34         print OUT "[[auto_$id]]\n";
  35         if($head =~ /\w+\([^()]*\)/ && $head !~ /\n/) {
  36                 print OUT "!!f!$head!!!\n\n";
  37         } else {
  38                 print OUT "..................\n";
  39                 print OUT "$head\n";
  40                 print OUT "..................\n\n";
  41         }
  42         if( $hasdump ) {
  43                 $head =~ s/\n.*//s;
  44                 print DUMP "$outname,$id,$head\n";
  45                 $id ++;
  46         }
  47         print OUT "$comment\n\n";
  48 }
  49
  50 sub process( $ ) {
  51         my $file = shift;
  52         open FILE, $file or die "Could nod read $file ($!)\n";
  53         my $line;
  54         my $active;
  55         my $verbatim;
  56         my $buff;
  57         my $head;
  58         my $struct;
  59         while( defined( $line = <FILE> ) ) {
  60                 chomp $line;
  61                 if( $struct ) {
  62                         $head .= "\n".$line;
  63                         if( $line =~ /}/ ) {
  64                                 formatNote( $head, $buff );
  65                                 $struct = 0;
  66                                 $buff = undef;
  67                                 $head = undef;
  68                         }
  69                 } elsif( $verbatim ) {
  70                         if( $line =~ /\*\// ) {
  71                                 $verbatim = 0;
  72                                 print OUT "\n";
  73                         } else {
  74                                 $line =~ s/^\s*\* ?//;
  75                                 print OUT "$line\n";
  76                         }
  77                 } elsif( $active ) {
  78                         if( $line =~ /\*\// ) {
  79                                 $active = 0;
  80                         } else {
  81                                 $line =~ s/^\s*\* ?//;
  82                                 $buff .= "$line\n";
  83                         }
  84                 } else {
  85                         if( ( $line =~ /\S/ ) && ( defined $buff ) ) {
  86                                 if( $line =~ /\(/ || $line !~ /{/ ) {
  87                                         $_ = $line;
  88                                         s/^\s*\s?//;
  89                                         s/\/\/.*//;
  90                                         s/\/\*.*?\*\///gs;
  91                                         s/([;{]).*/";"x length( $1 )/e;
  92                                         s/\)\s*;$/);/;
  93                                         formatNote( $_, $buff );
  94                                         $head = undef;
  95                                         $buff = undef;
  96                                 } else {
  97                                         $head = $line;
  98                                         $struct = 1;
  99                                 }
 100                         } elsif( ( $buff ) = ( $line =~ /\/\*\*\*(.*)\*\*\*\// ) ) {
 101                                 $buff =~ s/\s?//;
 102                                 print OUT "$buff\n\n";
 103                                 $buff = undef;
 104                         } elsif( ( $head, $buff ) = ( $line =~ /^(.*)\/\*\*(.*)\*\*\// ) ) {
 105                                 $buff =~ s/^\s*//;
 106                                 $buff =~ s/\s*$//;
 107                                 if( $head =~ /\(/ || $head !~ /{/ ) {
 108                                         $head =~ s/^\s*//;
 109                                         $head =~ s/\/\*.*?\*\///gs;
 110                                         $head =~ s/([;{]).*/";"x length( $1 )/e;
 111                                         $head =~ s/\)\s*;$/);/;
 112                                         formatNote( $head, $buff );
 113                                         $head = undef;
 114                                         $buff = undef;
 115                                 } else {
 116                                         $struct = 1;
 117                                 }
 118                         } elsif( $line =~ /\/\*\*\*/ ) {
 119                                 $verbatim = 1;
 120                         } elsif( $line =~ /\/\*\*/ ) {
 121                                 $active = 1;
 122                         }
 123                 }
 124         }
 125         close FILE;
 126 }
 127
 128 my $line;
 129 while( defined( $line = <IN> ) ) {
 130         chomp $line;
 131         if( my( $fname ) = ( $line =~ /^!!\s*(.*\S)/ ) ) {
 132                 $fname = "$basedir/$fname" if( ( $fname !~ /^\// ) && defined $basedir );
 133                 process( $fname );
 134                 push @deps, $fname;
 135         } else {
 136                 print OUT "$line\n";
 137         }
 138 }
 139
 140 if( defined $depname ) {
 141         open DEP, ">>$depname" or die "Could not write dep file $depname ($!)\n";
 142         print DEP "$outname:";
 143         print DEP " $_" foreach( @deps );
 144         print DEP "\n";
 145         if( $hasdump ) {
 146                 print DEP "$defdump:";
 147                 print DEP " $_" foreach( @deps );
 148                 print DEP "\n";
 149         }
 150         close DEP;
 151 }
 152
 153 close IN;
 154 close OUT;
 155 close DUMP;