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 421e1d3688a6e27611e37b963cf64bc59e7e5f5c..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;
 
@@ -22,14 +25,19 @@ if( defined $depname ) {
 print DEP "$outname:" if( $hasdep );
 
 sub formatNote( $$ ) {
-        my( $head, $comment ) = @_;
-       $head =~ s/[\t ]+/ /g;
+       my( $head, $comment ) = @_;
+       $head =~ s/(\S)[ ]+/$1 /g;
        print OUT "\n";
-        print OUT "''''\n";
-       print OUT "..................\n";
-        print OUT "$head\n";
-        print OUT "..................\n\n";
-        print OUT "$comment\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( $ ) {
@@ -54,6 +62,7 @@ sub process( $ ) {
                } elsif( $verbatim ) {
                        if( $line =~ /\*\// ) {
                                $verbatim = 0;
+                               print OUT "\n";
                        } else {
                                $line =~ s/^\s*\* ?//;
                                print OUT "$line\n";
@@ -63,7 +72,6 @@ sub process( $ ) {
                                $active = 0;
                        } else {
                                $line =~ s/^\s*\* ?//;
-                               $line =~ s/^\s*$/+/;
                                $buff .= "$line\n";
                        }
                } else {
@@ -72,7 +80,7 @@ sub process( $ ) {
                                        $_ = $line;
                                        s/^\s*\s?//;
                                        s/\/\/.*//;
-                                       s/\/\*.*?\*\///gs;
+                                       s/\/\*.*?\*\///gs;
                                        s/[;{].*//;
                                        formatNote( $_, $buff );
                                        $head = undef;
@@ -81,13 +89,17 @@ sub process( $ ) {
                                        $head = $line;
                                        $struct = 1;
                                }
+                       } 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/([;{]).*/$1/;
+                                       $head =~ s/[;{].*//;
                                        formatNote( $head, $buff );
                                        $head = undef;
                                        $buff = undef;