Add a description of extract-doc.pl script

[libucw.git] / build / extract-doc.pl

diff --git a/build/extract-doc.pl b/build/extract-doc.pl
index dca2e53deef6fc536b37f1abc20c5f82112d23fb..7eb28354f699ed9eb705a33934625dbae93fc6e3 100755 (executable)
--- a/build/extract-doc.pl
+++ b/build/extract-doc.pl
@@ -1,4 +1,7 @@
 #!/usr/bin/perl
+# Script for extracting documentation out of header files
+# (c) 2008 Michal Vaner <vorner@ucw.cz>
+
 use strict;
 use warnings;
 
@@ -21,6 +24,22 @@ if( defined $depname ) {
 
 print DEP "$outname:" if( $hasdep );
 
+sub formatNote( $$ ) {
+       my( $head, $comment ) = @_;
+       $head =~ s/(\S)[ ]+/$1 /g;
+       print OUT "\n";
+       print OUT "''''\n";
+       chomp $head;
+       if($head =~ /\w+\([^()]*\)/ && $head !~ /\n/) {
+               print OUT "!!f!$head!!!\n\n";
+       } else {
+               print OUT "..................\n";
+               print OUT "$head\n";
+               print OUT "..................\n\n";
+       }
+       print OUT "$comment\n\n";
+}
+
 sub process( $ ) {
        my $file = shift;
        open FILE, $file or die "Could nod read $file ($!)\n";
@@ -29,13 +48,21 @@ sub process( $ ) {
        my $verbatim;
        my $buff;
        my $head;
-       my $levelMark = '-';
-       my $markDepth;
+       my $struct;
        while( defined( $line = <FILE> ) ) {
                chomp $line;
-               if( $verbatim ) {
+               if( $struct ) {
+                       $head .= "\n".$line;
+                       if( $line =~ /}/ ) {
+                               formatNote( $head, $buff );
+                               $struct = 0;
+                               $buff = undef;
+                               $head = undef;
+                       }
+               } elsif( $verbatim ) {
                        if( $line =~ /\*\// ) {
                                $verbatim = 0;
+                               print OUT "\n";
                        } else {
                                $line =~ s/^\s*\* ?//;
                                print OUT "$line\n";
@@ -45,39 +72,40 @@ sub process( $ ) {
                                $active = 0;
                        } else {
                                $line =~ s/^\s*\* ?//;
-                               $line =~ s/^\s*$/+/;
                                $buff .= "$line\n";
                        }
                } else {
                        if( ( $line =~ /\S/ ) && ( defined $buff ) ) {
-                               chomp $line;
-                               $line =~ s/^\s*//;
-                               $line =~ s/\/\/.*//;
-                               $head .= "\n$line";
-                               if( $head =~ /[;{]/ ) {
-                                       $head =~ s/\/\*.*?\*\///gs;
-                                       $head =~ s/\s+/ /g;
-                                       $head =~ s/([;{]).*/$1/;
-                                       print OUT $levelMark." + +++$head+++ +\n+\n$buff\n";
-                                       if( $head =~ /\{/ ) {
-                                               $levelMark = '*' unless( $markDepth ++ );
-                                       }
+                               if( $line =~ /\(/ || $line !~ /{/ ) {
+                                       $_ = $line;
+                                       s/^\s*\s?//;
+                                       s/\/\/.*//;
+                                       s/\/\*.*?\*\///gs;
+                                       s/[;{].*//;
+                                       formatNote( $_, $buff );
                                        $head = undef;
                                        $buff = undef;
+                               } else {
+                                       $head = $line;
+                                       $struct = 1;
                                }
-                       } elsif( my( $head, $comment ) = ( $line =~ /^(.*)\/\*\*(.*)\*\*\// ) ) {
-                               $head =~ s/^\s*//;
-                               $head =~ s/\/\*.*?\*\///gs;
-                               $head =~ s/\s+/ /g;
-                               $head =~ s/([;{]).*/$1/;
-                               $comment =~ s/^\s*//;
-                               $comment =~ s/\s*$//;
-                               print OUT $levelMark." + +++$head+++ +\n+\n$comment\n\n";
-                               if( $head =~ /\{/ ) {
-                                       $levelMark = '*' unless( $markDepth ++ );
+                       } elsif( ( $buff ) = ( $line =~ /\/\*\*\*(.*)\*\*\*\// ) ) {
+                               $buff =~ s/\s?//;
+                               print OUT "$buff\n\n";
+                               $buff = undef;
+                       } elsif( ( $head, $buff ) = ( $line =~ /^(.*)\/\*\*(.*)\*\*\// ) ) {
+                               $buff =~ s/^\s*//;
+                               $buff =~ s/\s*$//;
+                               if( $head =~ /\(/ || $head !~ /{/ ) {
+                                       $head =~ s/^\s*//;
+                                       $head =~ s/\/\*.*?\*\///gs;
+                                       $head =~ s/[;{].*//;
+                                       formatNote( $head, $buff );
+                                       $head = undef;
+                                       $buff = undef;
+                               } else {
+                                       $struct = 1;
                                }
-                       } elsif( $line =~ /\}/ && $markDepth ) {
-                               $levelMark = '-' unless( -- $markDepth );
                        } elsif( $line =~ /\/\*\*\*/ ) {
                                $verbatim = 1;
                        } elsif( $line =~ /\/\*\*/ ) {