Rework lua document tool.

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

1 files changed, 110 insertions, 99 deletions

diff --git a/doc/lua_api.pl b/doc/lua_api.pl
index f608fbf8d..d40e463e4 100755
--- 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;