From e477d711138165f1bd6d7e82e4904fdedb4d8dde Mon Sep 17 00:00:00 2001 From: Vsevolod Stakhov Date: Wed, 27 Aug 2014 14:14:50 +0100 Subject: [PATCH] Rework lua document tool. - Allow @method and @function - Convert from unordered hash tables to arrays - Consider perl style guide --- doc/lua_api.pl | 209 ++++++++++++++++++++++++++----------------------- 1 file 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 <{'data'} EOD - if ($m->{'example'}) { - print <{'example'} ) { + print <{'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 <{'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 <{'return'} && $f->{'return'}->{'description'} ) { + $_ = $f->{'return'}; + if ( $_->{'type'} ) { + print "- `\{$_->{'type'}\}`: $_->{'description'}\n"; + } + else { + print "- $_->{'description'}\n"; + } + } + else { + print "\tnothing\n"; + } + if ( $f->{'example'} ) { + print <{'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; -- 2.39.5