From ea925a05b1b64f75b16dffb2ee5c09dd329309d0 Mon Sep 17 00:00:00 2001 From: lighta Date: Sat, 7 Dec 2013 18:03:03 -0500 Subject: [PATCH] Update check-doc to allow only listing, (for IDE that require functions for markup langage) Add option for extra documentation file inc_scrtf and inc_atcf (for people who have their customs documented in other file, wich is probably best to avoid conflicts) --- tools/check-doc.pl | 155 ++++++++++++++++++++++++++++++--------------- 1 file changed, 103 insertions(+), 52 deletions(-) diff --git a/tools/check-doc.pl b/tools/check-doc.pl index 704139fc55..8599cabfda 100755 --- a/tools/check-doc.pl +++ b/tools/check-doc.pl @@ -7,23 +7,29 @@ use File::Basename; use Getopt::Long; my $sHelp = 0; -my $sCmd = $1; my $sAtcf = "../doc/atcommands.txt"; my $sSctf = "../doc/script_commands.txt"; my $sLeftOverChk = 0; +my $sCmd = "chk"; +my $sValidCmd = "ls|chk"; my $sTarget = "All"; my $sValidTarget = "All|Script|Atc"; +my $sInc_atcf = "../doc/atcommands2.txt"; +my $sInc_scrtf = "../doc/script_commands2.txt"; my($filename, $dir, $suffix) = fileparse($0); chdir $dir; #put ourself like was called in tool folder GetArgs(); -Main($sTarget); +Main($sCmd,$sTarget); sub GetArgs { GetOptions( + 'cmd=s' => \$sCmd, # wich command to run 'atcf=s' => \$sAtcf, #atc doc file 'scriptf=s' => \$sSctf, #script doc file - 'target=s' => \$sTarget, #Target (wich setup to run) + 'inc_atcf=s' => \$sInc_atcf, #include script doc file (for customs doc) + 'inc_scrtf=s' => \$sInc_scrtf, #include script doc file (for customs doc) + 'target=s' => \$sTarget, #Target (wich files to run-cmd into) 'leftover=i' => \$sLeftOverChk, #should we chk if all doc are linked to a src ? 'help!' => \$sHelp, ) or $sHelp=1; #display help if invalid option @@ -31,9 +37,12 @@ sub GetArgs { if( $sHelp ) { print "Incorect option specified, available option are:\n" ."\t --atcf filename => file (specify atcommand doc to use)\n" + ."\t --inc_atcf filename => include file (specify atcommand doc to use)\n" ."\t --scriptf filename => file (specify script doc to use)\n" + ."\t --inc_scrtf filename => include file (specify script doc to use)\n" ."\t --leftover=0|1 => should we run reverse chk for leftover in documentation ?\n" - ."\t --target => target (specify wich check to run [$sValidTarget])\n"; + ."\t --target => target (specify wich check to run [$sValidTarget])\n" + ."\t --cmd => cmd (specify wich command to run [(default)$sValidCmd])\n"; exit; } unless($sTarget =~ /$sValidTarget/i){ @@ -41,18 +50,31 @@ sub GetArgs { ."\t --target => target (specify wich check to run [(default)$sValidTarget])\n"; exit; } + unless($sCmd =~ /$sValidCmd/i){ + print "Incorect command specified, available command are:\n" + ."\t --cmd => cmd (specify wich command to run [(default)$sValidCmd])\n"; + exit; + } } -sub Main { my ($sCmd) = @_; - if($sCmd=~/both|all/i){ #both is keep as backard compatibility here cf check-doc.sh - $sCmd = "script|atc"; +sub Main { my ($sCmd,$sTarget) = @_; + if($sTarget=~/both|all/i){ #both is keep as backard compatibility here cf check-doc.sh + $sTarget = "script|atc"; } - if($sCmd=~/script/i){ #find which script commands are missing from doc/script_commands.txt - Script_Chk(); + if($sTarget=~/script/i){ #find which script commands are missing from doc/script_commands.txt + my $raSct_cmd = Script_GetCmd(); + if($sCmd =~ /ls/i) { + print "The list of script-command found are = \n[ @$raSct_cmd ] \n\n"; + } + if($sCmd =~ /chk/i) { Script_Chk($raSct_cmd); } } - if($sCmd=~/atc/i){ #find which atcommands are missing from doc/atcommands.txt - Atc_Chk(); + if($sTarget=~/atc/i){ #find which atcommands are missing from doc/atcommands.txt + my $raAct_cmd = Atc_GetCmd(); + if($sCmd =~ /ls/i) { + print "The list of atcommand found are = \n[ @$raAct_cmd ] \n\n"; + } + if($sCmd =~ /chk/i) { Atc_Chk($raAct_cmd); } } } @@ -70,13 +92,14 @@ sub Chk { my($raA,$raB) = @_; return \@aMissing; } -sub Script_Chk { +sub Script_GetCmd { my @aSct_src = ("../src/map/script.c","../src/custom/script_def.inc"); my @aDef_sct = (); - my @aDoc_sct = (); - my $raMiss_sct; foreach my $sSct_srcf (@aSct_src){ - open FILE_SRC, "<$sSct_srcf" || die "couldn't open file $sSct_srcf \n"; + unless(open FILE_SRC, "<$sSct_srcf") { + print "couldn't open file $sSct_srcf \n"; + next; + } while(){ next if($_ =~ /^#/); #ignoe include, define or macro if($_ =~ /BUILDIN_DEF|BUILDIN_DEF2/){ @@ -95,24 +118,38 @@ sub Script_Chk { } close FILE_SRC; } - open FILE_DOC, "$sSctf" || die "couldn't open file $sSctf \n"; - while(){ - next if($_ =~ /^\*\*|^\*\s|^\s+/); #discard **, * foo, foo - next if(/^\s+/); - if($_ =~ /^\*/){ - my @line = split(' ',$_); - @line = split('\(',$line[0]); - @line = split('\<',$line[0]); - $line[0] =~ s/\(|\{|\*|\r|\s|\;|\)|\"|\,//g; #todo please harmonize command definition for easier parse - - next if($line[0] eq "Name" || $line[0] eq "" || $line[0] eq "function" - || $line[0] eq "if" || $line[0] eq "while" || $line[0] eq "do" || $line[0] eq "for" ); #exception list - - push(@aDoc_sct,$line[0]); + return \@aDef_sct; +} + +sub Script_Chk { my ($raDef_sct) = @_; + my @aSct_docf = ($sSctf,$sInc_scrtf); + my @aDoc_sct = (); + my $raMiss_sct; + + foreach my $sSct_docf (@aSct_docf){ + unless(open FILE_DOC, "$sSct_docf"){ + print "couldn't open file $sSct_docf \n"; + next; } + while(){ + next if($_ =~ /^\*\*|^\*\s|^\s+/); #discard **, * foo, foo + next if(/^\s+/); + if($_ =~ /^\*/){ + my @line = split(' ',$_); + @line = split('\(',$line[0]); + @line = split('\<',$line[0]); + $line[0] =~ s/\(|\{|\*|\r|\s|\;|\)|\"|\,//g; #todo please harmonize command definition for easier parse + + next if($line[0] eq "Name" || $line[0] eq "" || $line[0] eq "function" + || $line[0] eq "if" || $line[0] eq "while" || $line[0] eq "do" || $line[0] eq "for" ); #exception list + + push(@aDoc_sct,$line[0]); + } + } + close FILE_DOC; } - close FILE_DOC; - $raMiss_sct = Chk(\@aDef_sct,\@aDoc_sct); #check missing documentation + + $raMiss_sct = Chk($raDef_sct,\@aDoc_sct); #check missing documentation if(scalar(@$raMiss_sct)){ print "Missing script documentation for function :{\n"; foreach(@$raMiss_sct){ @@ -123,7 +160,7 @@ sub Script_Chk { else { print "All script command in Src are documented, no issues found\n"; } if($sLeftOverChk){ - my $raLeftover_sct = Chk(\@aDoc_sct,\@aDef_sct); #we just inverse the chk for leftover + my $raLeftover_sct = Chk(\@aDoc_sct,$raDef_sct); #we just inverse the chk for leftover if(scalar(@$raLeftover_sct)){ print "Those script command was found in doc but no source associated, leftover ? :{\n"; foreach(@$raLeftover_sct){ @@ -135,15 +172,16 @@ sub Script_Chk { } } -sub Atc_Chk { +sub Atc_GetCmd { my @aAct_src = ("../src/map/atcommand.c","../src/custom/atcommand_def.inc"); my @aDef_act = (); - my @aDoc_act = (); - my $raMiss_act; foreach my $sAct_srcf (@aAct_src){ - open FILE_SRC, "<$sAct_srcf" || die "couldn't open file $sAct_srcf \n"; + unless(open FILE_SRC, "<$sAct_srcf"){ + print "couldn't open file $sAct_srcf \n"; + next; + } while(){ - next if($_ =~ /^#/); #ignoe include, define or macro + next if($_ =~ /^#/); #ignore include, define or macro if($_ =~ /ACMD_DEF|ACMD_DEF2|ACMD_DEFR|ACMD_DEF2R/){ $_ =~ s/\s+$//; #Remove trailing spaces. $_ =~ s/^\s+//; #Remove leading spaces. @@ -162,21 +200,34 @@ sub Atc_Chk { } close FILE_SRC; } - open FILE_DOC, "$sAtcf" || die "couldn't open file $sAtcf \n"; - while(){ - next if($_ =~ /^\*\*|^\*\s|^\s+/); #discard **, * foo, foo - next if(/^\s+/); - if($_ =~ /^\@/){ - my @line = split(' ',$_); - @line = split('\(',$line[0]); - @line = split('\<',$line[0]); - $line[0] =~ s/\(|\{|\@|\r|\s|\;|\)|\"|\,//g; #todo please harmonize command definition for easier parse - push(@aDoc_act,$line[0]); - } - } - close FILE_DOC; + return \@aDef_act; +} + +sub Atc_Chk { my ($raDef_act) = @_; + my @aAct_docf = ($sAtcf,$sInc_atcf); + my @aDoc_act = (); + my $raMiss_act; - $raMiss_act = Chk(\@aDef_act,\@aDoc_act); #check missing documentation + foreach my $sAct_docf (@aAct_docf){ + unless(open FILE_DOC, "$sAct_docf"){ + print "couldn't open file $sAct_docf \n"; + next; + } + while(){ + next if($_ =~ /^\*\*|^\*\s|^\s+/); #discard **, * foo, foo + next if(/^\s+/); + if($_ =~ /^\@/){ + my @line = split(' ',$_); + @line = split('\(',$line[0]); + @line = split('\<',$line[0]); + $line[0] =~ s/\(|\{|\@|\r|\s|\;|\)|\"|\,//g; #todo please harmonize command definition for easier parse + push(@aDoc_act,$line[0]); + } + } + close FILE_DOC; + } + + $raMiss_act = Chk($raDef_act,\@aDoc_act); #check missing documentation if(scalar(@$raMiss_act)){ print "Missing atcommand documentation for function :{\n"; foreach(@$raMiss_act){ @@ -187,7 +238,7 @@ sub Atc_Chk { else { print "All atcommand in Src are documented, no issues found\n"; } if($sLeftOverChk){ - my $raLeftover_sct = Chk(\@aDoc_act,\@aDef_act); #we just inverse the chk for leftover + my $raLeftover_sct = Chk(\@aDoc_act,$raDef_act); #we just inverse the chk for leftover if(scalar(@$raLeftover_sct)){ print "Those atcommand command was found in doc but no source associated, leftover ? : {\n"; foreach(@$raLeftover_sct){