Rework lua document tool.

- Allow @method and @function
- Convert from unordered hash tables to arrays
- Consider perl style guide

diff --git a/doc/lua_api.pl b/doc/lua_api.pl
index f608fbf8d952bda00834bccefd877d0a9b60af53..d40e463e417644790c3f9e58ffe08961e1c8715a 100755 (executable)
--- a/doc/lua_api.pl
+++ b/doc/lua_api.pl
@@ -6,44 +6,25 @@ use Data::Dumper;
 use Storable qw/dclone/;
 
 use constant {
-       STATE_READ_SKIP => 0,
+       STATE_READ_SKIP    => 0,
        STATE_READ_CONTENT => 1,
 };
 
 my $state = STATE_READ_SKIP;
 my $content;
-my %functions = ();
 my %modules = ();
 my $cur_module;
 
-sub sort_func {
-       my ($a, $b) = @_;
+sub print_module_markdown {
+       my ( $mname, $m ) = @_;
 
-       if ($a =~ /^rspamd_[a-z]+\..*$/) {
-               if ($b =~ /^rspamd_[a-z]+\..*$/) {
-                       # All module names
-                       return $a cmp $b;
-               }
-               else {
-                       return -1;
-               }
-       }
-       elsif ($b =~ /^rspamd_[a-z]+\..*$/) {
-               return 1;
-       }
-       
-       return $a cmp $b;
-}
-
-sub print_markdown {
-       while (my ($mname, $m) = each %modules) {
-               print <<EOD;
-#$mname {#mod_$mname}
+       print <<EOD;
+#Module `$mname` {#mod_$mname}
 
 $m->{'data'}
 EOD
-               if ($m->{'example'}) {
-                       print <<EOD;
+       if ( $m->{'example'} ) {
+               print <<EOD;
 
 Example:
 
@@ -51,44 +32,47 @@ Example:
 $m->{'example'}
 ~~~
 EOD
-               }
-               print "\n##Methods\n\nThe module defines the following methods.\n\n";
-               foreach my $fname (sort {sort_func($a, $b)} keys %{$m->{'functions'}}) {
-                       my $f = $m->{'functions'}{$fname};
-                       print <<EOD;
+       }
+}
+
+sub print_function_markdown {
+       my ( $fname, $f ) = @_;
+
+       print <<EOD;
 ##`$fname`
 
 $f->{'data'}
 EOD
-                       print "\n**Parameters:**\n\n";
-                       if ($f->{'params'} && scalar @{$f->{'params'}} > 0) {
-                               foreach (@{$f->{'params'}}) {
-                                       if ($_->{'type'}) {
-                                               print "- `$_->{'name'} \{$_->{'type'}\}`: $_->{'description'}\n";
-                                       }
-                                       else {
-                                               print "- `$_->{'name'}`: $_->{'description'}\n";
-                                       }
-                               }
-                       }
-                       else {
-                               print "\tnothing\n";
-                       }
-                       print "\n**Returns:**\n\n";
-                       if ($f->{'return'} && $f->{'return'}->{'description'}) {
-                               $_ = $f->{'return'};
-                               if ($_->{'type'}) {
-                                       print "- `\{$_->{'type'}\}`: $_->{'description'}\n";
-                               }
-                               else {
-                                       print "- $_->{'description'}\n";
-                               }
+       print "\n**Parameters:**\n\n";
+       if ( $f->{'params'} && scalar @{ $f->{'params'} } > 0 ) {
+               foreach ( @{ $f->{'params'} } ) {
+                       if ( $_->{'type'} ) {
+                               print
+                                 "- `$_->{'name'} \{$_->{'type'}\}`: $_->{'description'}\n";
                        }
                        else {
-                               print "\tnothing\n";
+                               print "- `$_->{'name'}`: $_->{'description'}\n";
                        }
-                       if ($f->{'example'}) {
-                               print <<EOD;
+               }
+       }
+       else {
+               print "\tnothing\n";
+       }
+       print "\n**Returns:**\n\n";
+       if ( $f->{'return'} && $f->{'return'}->{'description'} ) {
+               $_ = $f->{'return'};
+               if ( $_->{'type'} ) {
+                       print "- `\{$_->{'type'}\}`: $_->{'description'}\n";
+               }
+               else {
+                       print "- $_->{'description'}\n";
+               }
+       }
+       else {
+               print "\tnothing\n";
+       }
+       if ( $f->{'example'} ) {
+               print <<EOD;
 
 Example:
 
@@ -96,28 +80,45 @@ Example:
 $f->{'example'}
 ~~~
 EOD
-                       }
+       }
+}
+
+sub print_markdown {
+       while ( my ( $mname, $m ) = each %modules ) {
+               print_module_markdown( $mname, $m );
+
+               print "\n##Functions\n\nThe module defines the following functions.\n\n";
+               foreach ( @{ $m->{'functions'} } ) {
+                       print_function_markdown( $_->{'name'}, $_ );
                        print "\nBack to [module description](#mod_$mname).\n\n";
-                       
+
+               }
+               print "\n##Methods\n\nThe module defines the following methods.\n\n";
+               foreach ( @{ $m->{'methods'} } ) {
+                       print_function_markdown( $_->{'name'}, $_ );
+                       print "\nBack to [module description](#mod_$mname).\n\n";
+
                }
                print "\nBack to [top](#).\n\n";
        }
 }
 
 sub parse_function {
-       my ($func, @data) = @_;
-       
-       my ($name) = ($func =~ /^\@function\s*(.+)\s*$/);
+       my ( $func, @data ) = @_;
+
+       my ( $type, $name ) = ( $func =~ /^\@(\w+)\s*(.+)\s*$/ );
 
-       $functions{$name} = {};
-       
-       my $f = $functions{$name};
+       my $f = {
+               name    => $name,
+               data    => '',
+               example => undef,
+       };
        my $example = 0;
 
-       foreach(@data) {
+       foreach (@data) {
                if (/^\@param\s*(?:\{([^}]+)\})?\s*(\S+)\s*(.+)?\s*$/) {
-                       my $p = { name => $2, type => $1, description => $3};
-                       push @{$f->{'params'}}, $p;
+                       my $p = { name => $2, type => $1, description => $3 };
+                       push @{ $f->{'params'} }, $p;
                }
                elsif (/^\@return\s*(?:\{([^}]+)\})?\s*(.+)?\s*$/) {
                        my $r = { type => $1, description => $2 };
@@ -126,7 +127,7 @@ sub parse_function {
                elsif (/^\@example$/) {
                        $example = 1;
                }
-               elsif ($_ ne $func) {
+               elsif ( $_ ne $func ) {
                        if ($example) {
                                $f->{'example'} .= $_;
                        }
@@ -135,29 +136,40 @@ sub parse_function {
                        }
                }
        }
-       if ($f->{'data'}) {
+       if ( $f->{'data'} ) {
                chomp $f->{'data'};
        }
-       if ($f->{'example'}) {
-               chomp $f->{'example'};  
+       if ( $f->{'example'} ) {
+               chomp $f->{'example'};
+       }
+
+       if ( $type eq "function" ) {
+               push @{ $cur_module->{'functions'} }, $f;
+       }
+       else {
+               push @{ $cur_module->{'methods'} }, $f;
        }
 }
 
 sub parse_module {
-       my ($module, @data) = @_;
-       
-       my ($name) = ($module =~ /^\@module\s*(.+)\s*$/);
-       $modules{$name} = { functions => dclone(\%functions) };
-       %functions = ();
-       
-       my $f = $modules{$name};
+       my ( $module, @data ) = @_;
+
+       my ($name) = ( $module =~ /^\@module\s*(.+)\s*$/ );
+
+       $modules{$name} = {
+               functions => [],
+               methods   => [],
+               data      => '',
+               example   => undef,
+       };
+       my $f       = $modules{$name};
        my $example = 0;
 
-       foreach(@data) {
+       foreach (@data) {
                if (/^\@example$/) {
                        $example = 1;
                }
-               elsif ($_ ne $module) {
+               elsif ( $_ ne $module ) {
                        if ($example) {
                                $f->{'example'} .= $_;
                        }
@@ -166,43 +178,43 @@ sub parse_module {
                        }
                }
        }
-       if ($f->{'data'}) {
+       if ( $f->{'data'} ) {
                chomp $f->{'data'};
        }
-       if ($f->{'example'}) {
-               chomp $f->{'example'};  
+       if ( $f->{'example'} ) {
+               chomp $f->{'example'};
        }
        $cur_module = $f;
 }
 
 sub parse_content {
-       my @func = grep /^\@function.+$/, @_;
-       if (scalar @func > 0) {
-               parse_function($func[0], @_);
+       my @func = grep /^\@function|method.+$/, @_;
+       if ( scalar @func > 0 ) {
+               parse_function( $func[0], @_ );
        }
        else {
                my @module = grep /^\@module.+$/, @_;
-               if (scalar @module > 0) {
-                       parse_module($module[0], @_);   
+               if ( scalar @module > 0 ) {
+                       parse_module( $module[0], @_ );
                }
        }
 }
 
-while(<>) {
-       if ($state == STATE_READ_SKIP) { 
-               if ($_ =~ /^\s*\/\*\*\*$/) {
-                       $state = STATE_READ_CONTENT;
+while (<>) {
+       if ( $state == STATE_READ_SKIP ) {
+               if ( $_ =~ /^\s*\/\*\*\*$/ ) {
+                       $state   = STATE_READ_CONTENT;
                        $content = "";
                }
        }
-       elsif ($state == STATE_READ_CONTENT) {
-               if ($_ =~ /^\s*\*\/$/) {
+       elsif ( $state == STATE_READ_CONTENT ) {
+               if ( $_ =~ /^\s*\*\/$/ ) {
                        $state = STATE_READ_SKIP;
-                       parse_content(split /^/, $content);
+                       parse_content( split /^/, $content );
                        $content = "";
                }
                else {
-                       my ($line) = ($_ =~ /^\s*(?:\*\s?)(.+)\s*$/);
+                       my ($line) = ( $_ =~ /^\s*(?:\*\s?)(.+)\s*$/ );
                        if ($line) {
                                $content .= $line . "\n";
                        }
@@ -214,6 +226,5 @@ while(<>) {
        }
 }
 
-$cur_module->{'functions'} = dclone(\%functions);
-#print Dumper(\%modules);
+#print Dumper( \%modules );
 print_markdown;