Filter/Perl.pm

filter: Statementstmt 18.4% 101 / 549 Branchbran 6.8% 14 / 206 Conditioncond 5.3% 4 / 75 MC/DCmcdc 0.0% 0 / 44 Subroutinesub 55.5% 20 / 36 Podpod 0.0% 0 / 11 totaltotal 15.0% 139 / 921 CC 139 SCAR 62.4
CC
139
Cov
14%
_ProcessDoxygenCommentBlock
1332.0
ProcessFile
825.4
_ProcessPerlMethod
272.0
CRAP 515.3
↑ Summary Filter/Perl/POD.pm »
1 #** @file Perl.pm
2 # @verbatim
3 #####################################################################
4 # This program is not guaranteed to work at all, and by using this #
5 # program you release the author of any and all liability. #
6 # #
7 # You may use this code as long as you are in compliance with the #
8 # license (see the LICENSE file) and this notice, disclaimer and #
9 # comment box remain intact and unchanged. #
10 # #
11 # Package: Doxygen::Filter #
12 # Class: Perl #
13 # Description: Methods for prefiltering Perl code for Doxygen #
14 # #
15 # Written by: Bret Jordan (jordan at open1x littledot org) #
16 # Created: 2011-10-13 #
17 #####################################################################
18 # @endverbatim
19 #
20 # @copy 2011, Bret Jordan (jordan2175@gmail.com, jordan@open1x.org)
21 #*
22 package Doxygen::Filter::Perl;
23  
24 1 ▶use 5.8.8;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 1 ▶use parent qw(Doxygen::Filter);
Subroutine BEGIN: called CC=1 SCAR=0.0
28 1 ▶use Log::Log4perl;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 1 ▶use Pod::POM;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 1 ▶use IO::Handle;
Subroutine BEGIN: called CC=1 SCAR=0.0
31 1 ▶use Doxygen::Filter::Perl::POD;
Subroutine BEGIN: called CC=1 SCAR=0.0
32  
33 1 our $VERSION = '1.73';
34 1 $VERSION = eval $VERSION;
35  
36  
37 # Define State Engine Values
38 1 my $hValidStates = {
39 'NORMAL' => 0,
40 'COMMENT' => 1,
41 'DOXYGEN' => 2,
42 'POD' => 3,
43 'METHOD' => 4,
44 'DOXYFILE' => 21,
45 'DOXYCLASS' => 22,
46 'DOXYFUNCTION' => 23,
47 'DOXYMETHOD' => 24,
48 'DOXYCOMMENT' => 25,
49 };
50  
51  
52 1 our %SYSTEM_PACKAGES = map({ $_ => 1 } qw(
53 base
54 warnings
55 strict
56 Exporter
57 vars
58 ));
59  
60  
61  
62 sub new
63 1 ▶{
Subroutine new: called CC=2 SCAR=7.1
Pod undocumented
64 #** @method private new ()
65 # This is the constructor and it calls _init() to initiate
66 # the various variables
67 #*
68 1 my $pkg = shift;
69 1 ▶ my $class = ref($pkg) || $pkg;
Condition33%1/3
ref $pkg || $pkg
l!l&&r!l&&!r
010
MC/DC0%0/2
ref $pkg || $pkg
ref $pkg $pkg
Truth table33%1/3
A || B
A= ref $pkgB= $pkg
ABresult
1X1
011
000
70
71 1 my $self = {};
72 1 bless ($self, $class);
73  
74 # Lets send any passed in arguments to the _init method
75 1 $self->_init(@_);
76 1 return $self;
77 }
78  
79 sub DESTROY
80 1 ▶{
Subroutine DESTROY: called CC=1 SCAR=0.0
81 #** @method private DESTROY ()
82 # This is the destructor
83 #*
84 1 my $self = shift;
85 1 $self = {};
86 }
87  
88 sub RESETSUB
89 1 ▶{
Subroutine RESETSUB: called CC=1 SCAR=0.0
Pod undocumented
90 1 my $self = shift;
91 1 $self->{'_iOpenBrace'} = 0;
92 1 $self->{'_iCloseBrace'} = 0;
93 1 $self->{'_sCurrentMethodName'} = undef;
94 1 $self->{'_sCurrentMethodType'} = undef;
95 1 $self->{'_sCurrentMethodState'} = undef;
96 }
97  
98 1 ▶sub RESETFILE { shift->{'_aRawFileData'} = []; }
Subroutine RESETFILE: called CC=1 SCAR=0.0
Pod undocumented
99  
100 sub RESETCLASS
101 1 ▶{
Subroutine RESETCLASS: called CC=1 SCAR=0.0
Pod undocumented
102 1 my $self = shift;
103 #$self->{'_sCurrentClass'} = 'main';
104 #push (@{$self->{'_hData'}->{'class'}->{'classorder'}}, 'main');
105 1 $self->_SwitchClass('main');
106 }
107  
108 1 ▶sub RESETDOXY { shift->{'_aDoxygenBlock'} = []; }
Subroutine RESETDOXY: called CC=1 SCAR=0.0
Pod undocumented
109 1 ▶sub RESETPOD { shift->{'_aPodBlock'} = []; }
Subroutine RESETPOD: called CC=1 SCAR=0.0
Pod undocumented
110  
111  
112  
113 sub _init
114 1 ▶{
Subroutine _init: called CC=1 SCAR=0.0
115 #** @method private _init ()
116 # This method is used in the constructor to initiate
117 # the various variables in the object
118 #*
119 1 my $self = shift;
120 1 $self->{'_iDebug'} = 0;
121 1 $self->{'_sState'} = undef;
122 1 $self->{'_sPreviousState'} = [];
123 1 $self->_ChangeState('NORMAL');
124 1 $self->{'_hData'} = {};
125 1 $self->RESETFILE();
126 1 $self->RESETCLASS();
127 1 $self->RESETSUB();
128 1 $self->RESETDOXY();
129 1 $self->RESETPOD();
130 }
131  
132  
133  
134  
135 # ----------------------------------------
136 # Public Methods
137 # ----------------------------------------
138 sub GetCurrentClass
139 0 ▶{
Subroutine GetCurrentClass: not called CC=1 SCAR=6.9
Pod undocumented
140 0 my $self = shift;
141 0 return $self->{'_hData'}->{'class'}->{$self->{'_sCurrentClass'}};
142 }
143  
144 sub ReadFile
145 0 ▶{
Subroutine ReadFile: not called CC=1 SCAR=6.9
Pod undocumented
146 #** @method public ReadFile ($sFilename)
147 # This method will read the contents of the file in to an array
148 # and store that in the object as $self->{'_aRawFileData'}
149 # @param sFilename - required string (filename to use)
150 #*
151 0 my $self = shift;
152 0 my $sFilename = shift;
153 0 my $logger = $self->GetLogger($self);
154 0 $logger->debug("### Entering ReadFile ###");
155
156 # Lets record the file name in the data structure
157 0 $self->{'_hData'}->{'filename'}->{'fullpath'} = $sFilename;
158  
159 # Replace forward slash with a black slash
160 0 $sFilename =~ s/\\/\//g;
161 # Remove windows style drive letters
162 0 $sFilename =~ s/^.*://;
163
164 # Lets grab just the file name not the full path for the short name
165 0 $sFilename =~ /^(.*\/)*(.*)$/;
166 0 $self->{'_hData'}->{'filename'}->{'shortname'} = $2;
167
168 0 open(DATAIN, $sFilename);
169 #my @aFileData = <DATAIN>;
170 0 my @aFileData = map({ s/\r$//g; $_; } <DATAIN>);
171 0 close (DATAIN);
172 0 $self->{'_aRawFileData'} = \@aFileData;
173 }
174  
175 sub ReportError
176 0 ▶{
Subroutine ReportError: not called CC=2 SCAR=17.9
Pod undocumented
177 #** @method public void ReportError($message)
178 # @brief Reports an error message in the current context.
179 #
180 # The message is prepended by 'filename:lineno: error:' prefix so it is easily
181 # parseable by IDEs and advanced editors.
182 #*
183 0 my $self = shift;
184 0 my $message = shift;
185  
186 0 my $hData = $self->{'_hData'};
187 0 my $header = "$hData->{filename}->{fullpath}:$hData->{lineno}: error: ";
188 0 ▶ $message .= "\n" if (substr($message, -1, 1) ne "\n");
Branch: 1 branch
BranchTrueFalseTotal
if substr($message, -1, 1) ne "\n" 0 0 0
189 0 $message =~ s/^/$header/gm;
190 0 STDERR->print($message);
191 }
192  
193 sub ProcessFile
194 3 ▶{
Subroutine ProcessFile: called CC=38 SCAR=67.2
Pod undocumented
195 #** @method public ProcessFile ()
196 # This method is a state machine that will search down each line of code to see what it should do
197 #*
198 3 my $self = shift;
199 3 my $logger = $self->GetLogger($self);
200 3 $logger->debug("### Entering ProcessFile ###");
201  
202 3 $self->{'_hData'}->{'lineno'} = 0;
203 3 foreach my $line (@{$self->{'_aRawFileData'}})
204 {
205 7 $self->{'_hData'}->{'lineno'}++;
206 # Convert syntax block header to supported doxygen form, if this line is a header
207 7 $line = $self->_ConvertToOfficialDoxygenSyntax($line);
208
209 # Lets first figure out what state we SHOULD be in and then we will deal with
210 # processing that state. This first block should walk through all the possible
211 # transition states, aka, the states you can get to from the state you are in.
212 7 ▶ if ($self->{'_sState'} eq 'NORMAL')
Branch: 4 branches
BranchTrueFalseTotal
if ($self->{'_sState'} eq 'NORMAL') { } 7 0 7
elsif ($self->{'_sState'} eq 'METHOD') { } 0 0 0
elsif ($self->{'_sState'} eq 'DOXYGEN') { } 0 0 0
elsif ($self->{'_sState'} eq 'POD') { } 0 0 0
213 {
214 7 $logger->debug("We are in state: NORMAL");
215 0 ▶ if ($line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/) { $self->_ChangeState('METHOD'); }
Branch: 3 branches
BranchTrueFalseTotal
if ($line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/) { } 0 7 7
elsif ($line =~ /^\s*#\*\*\s*\@/) { } 0 7 7
elsif ($line =~ /^=.*/) { } 0 7 7
Condition33%1/3
$line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/
!ll&&!rl&&r
700
MC/DC0%0/2
$line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/
$line =~ /^\s*sub\s+([\w]+)/ $line =~ /^\s*sub\s+([\D][\w]*)/
Truth table33%1/3
A and B
A= $line =~ /^\s*sub\s+([\w]+)/B= $line =~ /^\s*sub\s+([\D][\w]*)/
ABresult
0X0
100
111
216 0 elsif ($line =~ /^\s*#\*\*\s*\@/) { $self->_ChangeState('DOXYGEN'); }
217 0 elsif ($line =~ /^=.*/) { $self->_ChangeState('POD'); }
218 }
219 elsif ($self->{'_sState'} eq 'METHOD')
220 {
221 0 $logger->debug("We are in state: METHOD");
222 0 ▶ if ($line =~ /^\s*#\*\*\s*\@/ ) { $self->_ChangeState('DOXYGEN'); }
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^\s*#\*\*\s*\@/) 0 0 0
223 }
224 elsif ($self->{'_sState'} eq 'DOXYGEN')
225 {
226 0 $logger->debug("We are in state: DOXYGEN");
227 # If there are no more comments, then reset the state to the previous state
228 0 ▶ unless ($line =~ /^\s*#/)
Branch: 1 branch
BranchTrueFalseTotal
unless ($line =~ /^\s*#/) 0 0 0
229 {
230 # The general idea is we gather the whole doxygen comment in to an array and process
231 # that array all at once in the _ProcessDoxygenCommentBlock. This way we do not have
232 # to artificially keep track of what type of comment block it is between each line
233 # that we read from the file.
234 0 $logger->debug("End of Doxygen Comment Block");
235 0 $self->_ProcessDoxygenCommentBlock();
236 0 $self->_RestoreState();
237 0 $logger->debug("We are in state $self->{'_sState'}");
238 0 ▶ if ($self->{'_sState'} eq 'NORMAL')
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"_sState"} eq "NORMAL") 0 0 0
239 {
240 # If this comment block is right next to a subroutine, lets make sure we
241 # handle that condition
242 0 ▶ if ($line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/) { $self->_ChangeState('METHOD'); }
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/) 0 0 0
Condition0%0/3
$line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/
!ll&&!rl&&r
000
MC/DC0%0/2
$line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/
$line =~ /^\s*sub\s+([\w]+)/ $line =~ /^\s*sub\s+([\D][\w]*)/
Truth table0%0/3
A and B
A= $line =~ /^\s*sub\s+([\w]+)/B= $line =~ /^\s*sub\s+([\D][\w]*)/
ABresult
0X0
100
111
243 }
244 }
245 }
246 elsif ($self->{'_sState'} eq 'POD')
247 {
248 0 ▶ if ($line =~ /^=cut/)
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^=cut/) 0 0 0
249 {
250 0 push (@{$self->{'_aPodBlock'}}, $line);
251 0 $self->_ProcessPodCommentBlock();
252 0 $self->_RestoreState();
253 }
254 }
255  
256  
257 # Process states
258 7 ▶ if ($self->{'_sState'} eq 'NORMAL')
Branch: 4 branches
BranchTrueFalseTotal
if ($self->{'_sState'} eq 'NORMAL') { } 7 0 7
elsif ($self->{'_sState'} eq 'METHOD') { } 0 0 0
elsif ($self->{'_sState'} eq 'DOXYGEN') { } 0 0 0
elsif ($self->{'_sState'} eq 'POD') { } 0 0 0
259 {
260 7 ▶ if ($line =~ /^\s*package\s*([^;]*)\;/)
Branch: 4 branches
BranchTrueFalseTotal
if ($line =~ /^\s*package\s*([^;]*)\;/) { } 0 7 7
elsif ($line =~ /our\s+\$VERSION\s*=\s*(.*);$/) { } 2 5 7
elsif ($line =~ /^\s*use\s+([\w:]+)(|\s*(\S.*?)\s*;*)$/) { } 0 5 5
elsif ($line =~ /^\s*(?:Readonly\s+)?(my|our)\s+(([\$\@%*])(\w+))([^=]*|\s*=\s*(\S.*?)\s*;*)$/) { } 0 5 5
261 {
262 #$self->{'_sCurrentClass'} = $1;
263 #push (@{$self->{'_hData'}->{'class'}->{'classorder'}}, $1);
264 0 $self->_SwitchClass($1);
265 }
266 elsif ($line =~ /our\s+\$VERSION\s*=\s*(.*);$/)
267 {
268 # our $VERSION = '0.99_01';
269 # use version; our $VERSION = qv('0.3.1'); - Thanks Hoppfrosch for the suggestion
270 2 my $version = $1;
271 2 $version =~ s/[\'\"\(\)\;]//g;
272 2 $version =~ s/qv//;
273 2 $self->{'_hData'}->{'filename'}->{'version'} = $version;
274 }
275 #elsif ($line =~ /^\s*use\s+([\w:]+)/)
276 elsif ($line =~ /^\s*use\s+([\w:]+)(|\s*(\S.*?)\s*;*)$/)
277 {
278 0 my $sIncludeModule = $1;
279 0 my $x = $2;
280 0 my $expr = $3;
281 0 ▶ if (defined($sIncludeModule))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sIncludeModule) 0 0 0
282 {
283 #unless ($sIncludeModule eq "strict" || $sIncludeModule eq "warnings" || $sIncludeModule eq "vars" || $sIncludeModule eq "Exporter" || $sIncludeModule eq "base")
284 0 ▶ if ($sIncludeModule =~ m/^(base|strict|warnings|vars|Exporter)$/)
Branch: 1 branch
BranchTrueFalseTotal
if ($sIncludeModule =~ /^(base|strict|warnings|vars|Exporter)$/) { } 0 0 0
285 {
286 0 ▶ if ($sIncludeModule eq "base")
Branch: 1 branch
BranchTrueFalseTotal
if ($sIncludeModule eq 'base') { } 0 0 0
287 {
288 0 ▶ if (substr($expr,0,8) =~ /\"require/) { }
Branch: 1 branch
BranchTrueFalseTotal
if (substr($expr, 0, 8) =~ /\"require/) { } 0 0 0
289 else
290 {
291 0 my @isa = eval($expr);
292 0 ▶ push(@{$self->GetCurrentClass()->{inherits}}, _FilterOutSystemPackages(@isa)) unless ($@);
Branch: 1 branch
BranchTrueFalseTotal
unless $@ 0 0 0
293 }
294 }
295 else
296 {
297 # ignore other system modules
298 }
299 }
300 else
301 {
302 # Allows doxygen to know where to look for other packages
303 0 $sIncludeModule =~ s/::/\//g;
304 0 push (@{$self->{'_hData'}->{'includes'}}, $sIncludeModule);
305 }
306 }
307 }
308 #elsif ($line =~ /^\s*(?:Readonly\s+)?(?:my|our)\s+([\$@%*]\w+)/)
309 #elsif ($line =~ /^\s*(?:Readonly\s+)?(my|our)\s+([\$@%*]\w+)([^=]*|\s*=\s*(\S.*?)\s*;*)$/)
310 elsif ($line =~ /^\s*(?:Readonly\s+)?(my|our)\s+(([\$@%*])(\w+))([^=]*|\s*=\s*(\S.*?)\s*;*)$/)
311 {
312 # Lets look for locally defined variables/arrays/hashes and capture them such as:
313 # my $var;
314 # my $var = ...
315 # our @var = ...
316 # Readonly our %var ...
317 #my $sAttrName = $1;
318 #if (defined($sAttrName) && $sAttrName !~ m/^(\@EXPORT|\@EXPORT_OK|\$VERSION)$/)
319 0 my $scope = $1;
320 0 my $fullName = $2;
321 0 my $typeCode = $3;
322 0 my $sAttrName = $4;
323 0 my $expr = $6;
324  
325 0 ▶ if (defined $sAttrName)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sAttrName) 0 0 0
326 {
327 #my $sClassName = $self->{'_sCurrentClass'};
328 #push (@{$self->{'_hData'}->{'class'}->{$sClassName}->{attributeorder}}, $sAttrName);
329 0 ▶ if ($scope eq "our" && $fullName =~ m/^(\@ISA|\@EXPORT|\@EXPORT_OK|\$VERSION)$/)
Branch: 1 branch
BranchTrueFalseTotal
if ($scope eq 'our' and $fullName =~ /^(\@ISA|\@EXPORT|\@EXPORT_OK|\$VERSION)$/) { } 0 0 0
Condition0%0/3
$scope eq "our" and $fullName =~ /^(\@ISA|\@EXPORT|\@EXPORT_OK|\$VERSION)$/
!ll&&!rl&&r
000
MC/DC0%0/2
$scope eq "our" and $fullName =~ /^(\@ISA|\@EXPORT|\@EXPORT_OK|\$VERSION)$/
$scope eq "our" $fullName =~ /^(\@ISA|\@EXPORT|\@EXPORT_OK|\$VERSION)$/
Truth table0%0/3
A and B
A= $scope eq "our"B= $fullName =~ /^(\@ISA|\@EXPORT|\@EXPORT_OK|\$VERSION)$/
ABresult
0X0
100
111
330 {
331 0 ▶ if ($fullName eq "\@ISA" && defined $expr)
Branch: 1 branch
BranchTrueFalseTotal
if ($fullName eq '@ISA' and defined $expr) { } 0 0 0
Condition0%0/3
$fullName eq "\@ISA" and defined $expr
!ll&&!rl&&r
000
MC/DC0%0/2
$fullName eq "\@ISA" and defined $expr
$fullName eq "\@ISA" defined $expr
Truth table0%0/3
A and B
A= $fullName eq "\@ISA"B= defined $expr
ABresult
0X0
100
111
332 {
333 0 my @isa = eval($expr);
334 0 ▶ push(@{$self->GetCurrentClass()->{inherits}}, _FilterOutSystemPackages(@isa)) unless ($@);
Branch: 1 branch
BranchTrueFalseTotal
unless $@ 0 0 0
335 }
336 else
337 {
338 # ignore other system variables
339 }
340 }
341 else
342 {
343 0 my $sClassName = $self->{'_sCurrentClass'};
344 0 ▶ if (!exists $self->{'_hData'}->{'class'}->{$sClassName}->{attributes}->{$sAttrName})
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"_hData"}{"class"}{$sClassName}{"attributes"}{$sAttrName}) 0 0 0
345 {
346 # only define the attribute if it was not yet defined by doxygen comment
347 0 ▶ my $attrDef = $self->{'_hData'}->{'class'}->{$sClassName}->{attributes}->{$sAttrName} = {
Branch: 1 branch
BranchTrueFalseTotal
$scope eq 'my' ? : 0 0 0
348 type => $self->_ConvertTypeCode($typeCode),
349 modifiers => "static ",
350 state => $scope eq "my" ? "private" : "public",
351 };
352 0 push(@{$self->{'_hData'}->{'class'}->{$sClassName}->{attributeorder}}, $sAttrName);
353 }
354 }
355 }
356 0 ▶ if ($line =~ /(#\*\*\s+\@.*$)/)
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /(#\*\*\s+\@.*$)/) 0 0 0
357 {
358 # Lets look for an single in-line doxygen comment on a variable, array, or hash declaration
359 0 my $sBlock = $1;
360 0 push (@{$self->{'_aDoxygenBlock'}}, $sBlock);
361 0 $self->_ProcessDoxygenCommentBlock();
362 }
363 }
364 }
365 0 elsif ($self->{'_sState'} eq 'METHOD') { $self->_ProcessPerlMethod($line); }
366 0 elsif ($self->{'_sState'} eq 'DOXYGEN') { push (@{$self->{'_aDoxygenBlock'}}, $line); }
367 0 elsif ($self->{'_sState'} eq 'POD') { push (@{$self->{'_aPodBlock'}}, $line);}
368 }
369 }
370  
371 sub PrintAll
372 0 ▶{
Subroutine PrintAll: not called CC=15 SCAR=54.8
Pod undocumented
373 #** @method public PrintAll ()
374 # This method will print out the entire data structure in a form that Doxygen can work with.
375 # It is important to note that you are basically making the output look like C code so that
376 # packages and classes need to have start and end blocks and need to include all of the
377 # elements that are part of that package or class
378 #*
379 0 my $self = shift;
380 0 my $logger = $self->GetLogger($self);
381 0 $logger->debug("### Entering PrintAll ###");
382  
383 0 binmode STDOUT, ":utf8";
384  
385 0 $self->_PrintFilenameBlock();
386 0 $self->_PrintIncludesBlock();
387
388 0 foreach my $class (@{$self->{'_hData'}->{'class'}->{'classorder'}})
389 {
390 0 my $classDef = $self->{'_hData'}->{'class'}->{$class};
391  
392 # skip the default main class unless we really have something to print
393 0 ▶ if ($class eq "main" &&
Branch: 1 branch
BranchTrueFalseTotal
if ($class eq "main" and @{$classDef->{"attributeorder"};} == 0 and @{$classDef->{"subroutineorder"};} == 0 and not defined $classDef->{"details"} and not defined $classDef->{"comments"}) 0 0 0
Condition0%0/12
$class eq "main" and @{$classDef->{"attributeorder"};} == 0 and @{$classDef->{"subroutineorder"};} == 0 and not defined $classDef->{"details"} and not defined $classDef->{"comments"}
!ll&&!rl&&r
000
$class eq "main" and @{$classDef->{"attributeorder"};} == 0 and @{$classDef->{"subroutineorder"};} == 0 and not defined $classDef->{"details"}
!ll&&!rl&&r
000
$class eq "main" and @{$classDef->{"attributeorder"};} == 0 and @{$classDef->{"subroutineorder"};} == 0
!ll&&!rl&&r
000
$class eq "main" and @{$classDef->{"attributeorder"};} == 0
!ll&&!rl&&r
000
MC/DC0%0/5
$class eq "main" and @{$classDef->{"attributeorder"};} == 0 and @{$classDef->{"subroutineorder"};} == 0 and not defined $classDef->{"details"} and not defined $classDef->{"comments"}
$class eq "main" @{$classDef->{"attributeorder"};} == 0 @{$classDef->{"subroutineorder"};} == 0 not defined $classDef->{"details"} not defined $classDef->{"comments"}
Truth table0%0/6
A and B and C and not(D) and not(E)
A= $class eq "main"B= @{$classDef->{"attributeorder"};} == 0C= @{$classDef->{"subroutineorder"};} == 0D= not defined $classDef->{"details"}E= not defined $classDef->{"comments"}
ABCDEresult
0XXXX0
10XXX0
110XX0
1110X0
111100
111111
394 0 @{$classDef->{attributeorder}} == 0 &&
395 0 @{$classDef->{subroutineorder}} == 0 &&
396 (!defined $classDef->{details}) &&
397 (!defined $classDef->{comments})
398 )
399 {
400 0 next;
401 }
402  
403 0 $self->_PrintClassBlock($class);
404  
405 # Print all available attributes first that are defined at the global class level
406 0 foreach my $sAttrName (@{$self->{'_hData'}->{'class'}->{$class}->{'attributeorder'}})
407 {
408 0 my $attrDef = $self->{'_hData'}->{'class'}->{$class}->{'attributes'}->{$sAttrName};
409  
410 0 ▶ my $sState = $attrDef->{'state'} || 'public';
Condition0%0/2
$attrDef->{'state'} || 'public'
l!l
00
MC/DC0%0/1
$attrDef->{'state'} || 'public'
$attrDef->{'state'}
Truth table0%0/2
A
A= $attrDef->{'state'}
Aresult
11
00
411 0 my $sComments = $attrDef->{'comments'};
412 0 my $sDetails = $attrDef->{'details'};
413 0 ▶ if (defined $sComments || defined $sDetails)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sComments or defined $sDetails) 0 0 0
Condition0%0/3
defined $sComments or defined $sDetails
l!l&&r!l&&!r
000
MC/DC0%0/2
defined $sComments or defined $sDetails
defined $sComments defined $sDetails
Truth table0%0/3
A or B
A= defined $sCommentsB= defined $sDetails
ABresult
1X1
011
000
414 {
415 0 print "/**\n";
416 0 ▶ if (defined $sComments)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sComments) 0 0 0
417 {
418 0 print " \* \@brief $sComments\n";
419 }
420  
421 0 ▶ if ($sDetails)
Branch: 1 branch
BranchTrueFalseTotal
if ($sDetails) 0 0 0
422 {
423 0 print " * \n".$sDetails;
424 }
425  
426 0 print " */\n";
427 }
428  
429 0 print("$sState:\n$attrDef->{modifiers}$attrDef->{type} $sAttrName;\n\n");
430 }
431
432 # Print all functions/methods in order of appearance, let doxygen take care of grouping them according to modifiers
433 # I added this print public line to make sure the functions print if one of
434 # the previous elements was a my $a = 1 and thus had a print "private:"
435 # This is no longer needed, fixed it in the Doxyfile instead.
436 # print("public:\n");
437 0 foreach my $methodName (@{$self->{'_hData'}->{'class'}->{$class}->{'subroutineorder'}})
438 {
439 0 $self->_PrintMethodBlock($class, $methodName);
440 }
441 # Print end of class mark
442 0 print "}\;\n";
443 # print end of namespace if class is nested
444 0 ▶ print "};\n" if ($class =~ /::/);
Branch: 1 branch
BranchTrueFalseTotal
if $class =~ /::/ 0 0 0
445 }
446 }
447  
448  
449 # ----------------------------------------
450 # Private Methods
451 # ----------------------------------------
452 sub _FilterOutSystemPackages
453 0 ▶{
Subroutine _FilterOutSystemPackages: not called CC=2 SCAR=17.9
454 0 ▶ if (!defined($_)) { return @_};
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $_) 0 0 0
455 0 return grep({ !exists $SYSTEM_PACKAGES{$_} } @_);
456 }
457  
458  
459 sub _SwitchClass
460 1 ▶{
Subroutine _SwitchClass: called CC=2 SCAR=7.0
461 1 my $self = shift;
462 1 my $class = shift;
463  
464 1 $self->{'_sCurrentClass'} = $class;
465 1 ▶ if (!exists $self->{'_hData'}->{'class'}->{$class})
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"_hData"}{"class"}{$class}) 1 0 1
466 {
467 1 push(@{$self->{'_hData'}->{'class'}->{'classorder'}}, $class);
468 1 $self->{'_hData'}->{'class'}->{$class} = {
469 classname => $class,
470 inherits => [],
471 attributeorder => [],
472 subroutineorder => [],
473 };
474 }
475  
476 1 return $self->{'_hData'}->{'class'}->{$class};
477 }
478  
479 0 ▶sub _RestoreState { shift->_ChangeState(); }
Subroutine _RestoreState: not called CC=1 SCAR=6.9
480 sub _ChangeState
481 1 ▶{
Subroutine _ChangeState: called CC=6 SCAR=24.4
482 #** @method private _ChangeState ($state)
483 # This method will change and keep track of the various states that the state machine
484 # transitions to and from. Having this information allows you to return to a previous
485 # state. If you pass nothing in to this method it will restore the previous state.
486 # @param state - optional string (state to change to)
487 #*
488 1 my $self = shift;
489 1 my $state = shift;
490 1 my $logger = $self->GetLogger($self);
491 1 $logger->debug("### Entering _ChangeState ###");
492
493 1 ▶ if (defined $state && exists $hValidStates->{$state})
Branch: 1 branch
BranchTrueFalseTotal
if (defined $state and exists $hValidStates->{$state}) { } 1 0 1
Condition33%1/3
defined $state and exists $hValidStates->{$state}
!ll&&!rl&&r
001
MC/DC0%0/2
defined $state and exists $hValidStates->{$state}
defined $state exists $hValidStates->{$state}
Truth table33%1/3
A and B
A= defined $stateB= exists $hValidStates->{$state}
ABresult
0X0
100
111
494 {
495 # If there was a value passed in and it is a valid value lets make it active
496 1 $logger->debug("State passed in: $state");
497 1 ▶ unless (defined $self->{'_sState'} && $self->{'_sState'} eq $state)
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_sState"} and $self->{"_sState"} eq $state) 1 0 1
Condition33%1/3
defined $self->{"_sState"} and $self->{"_sState"} eq $state
!ll&&!rl&&r
100
MC/DC0%0/2
defined $self->{"_sState"} and $self->{"_sState"} eq $state
defined $self->{"_sState"} $self->{"_sState"} eq $state
Truth table33%1/3
A and B
A= defined $self->{"_sState"}B= $self->{"_sState"} eq $state
ABresult
0X0
100
111
498 {
499 # Need to push the current state to the array BEFORE we change it and only
500 # if we are not currently at that state
501 1 push (@{$self->{'_sPreviousState'}}, $self->{'_sState'});
502 1 $self->{'_sState'} = $state;
503 }
504 }
505 else
506 {
507 # If nothing is passed in, lets set the current state to the previous state.
508 0 $logger->debug("No state passed in, lets revert to previous state");
509 0 my $previous = pop @{$self->{'_sPreviousState'}};
510 0 ▶ if (defined $previous)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $previous) { } 0 0 0
511 {
512 0 $logger->debug("Previous state was $previous");
513 }
514 else
515 {
516 0 $logger->error("There is no previous state! Setting to NORMAL");
517 0 $previous = 'NORMAL';
518 }
519 0 $self->{'_sState'} = $previous;
520 }
521 }
522  
523 sub _PrintFilenameBlock
524 0 ▶{
Subroutine _PrintFilenameBlock: not called CC=4 SCAR=30.0
525 #** @method private _PrintFilenameBlock ()
526 # This method will print the filename section in appropriate doxygen syntax
527 #*
528 0 my $self = shift;
529 0 my $logger = $self->GetLogger($self);
530 0 $logger->debug("### Entering _PrintFilenameBlock ###");
531
532 0 ▶ if (defined $self->{'_hData'}->{'filename'}->{'fullpath'})
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"_hData"}{"filename"}{"fullpath"}) 0 0 0
533 {
534 0 print "/** \@file \"$self->{'_hData'}->{'filename'}->{'fullpath'}\"\n";
535 0 ▶ if (defined $self->{'_hData'}->{'filename'}->{'details'}) { print "$self->{'_hData'}->{'filename'}->{'details'}\n"; }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"_hData"}{"filename"}{"details"}) 0 0 0
536 0 ▶ if (defined $self->{'_hData'}->{'filename'}->{'version'}) { print "\@version $self->{'_hData'}->{'filename'}->{'version'}\n"; }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"_hData"}{"filename"}{"version"}) 0 0 0
537 0 print "*/\n";
538 }
539 }
540  
541 sub _PrintIncludesBlock
542 0 ▶{
Subroutine _PrintIncludesBlock: not called CC=2 SCAR=17.9
543 #** @method private _PrintIncludesBlock ()
544 # This method will print the various extra modules that are used
545 #*
546 0 my $self = shift;
547 0 my $logger = $self->GetLogger($self);
548 0 $logger->debug("### Entering _PrintIncludeBlock ###");
549  
550 0 foreach my $include (@{$self->{'_hData'}->{'includes'}})
551 {
552 0 print "\#include \"$include.pm\"\n";
553 }
554 0 print "\n";
555 }
556  
557 sub _PrintClassBlock
558 0 ▶{
Subroutine _PrintClassBlock: not called CC=9 SCAR=45.0
559 #** @method private _PrintClassBlock ($sFullClass)
560 # This method will print the class/package block in appropriate doxygen syntax
561 # @param sFullClass - required string (full name of the class)
562 #*
563 0 my $self = shift;
564 0 my $sFullClass = shift;
565 0 my $logger = $self->GetLogger($self);
566 0 $logger->debug("### Entering _PrintClassBlock ###");
567  
568 # We need to reset the $1 / $2 match for perl scripts without package classes.
569 # so lets do it here just to be save. Yes this is an expensive way of doing it
570 # but it works.
571 0 $sFullClass =~ /./;
572 0 $sFullClass =~ /(.*)\:\:(\w+)$/;
573 0 my $parent = $1;
574 0 ▶ my $class = $2 || $sFullClass;
Condition0%0/3
$2 || $sFullClass
l!l&&r!l&&!r
000
MC/DC0%0/2
$2 || $sFullClass
$2 $sFullClass
Truth table0%0/3
A || B
A= $2B= $sFullClass
ABresult
1X1
011
000
575
576 0 print "/** \@class $sFullClass\n";
577  
578 0 my $classDef = $self->{'_hData'}->{'class'}->{$sFullClass};
579
580 0 my $details = $self->{'_hData'}->{'class'}->{$sFullClass}->{'details'};
581 0 ▶ if (defined $details) { print "$details\n"; }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $details) 0 0 0
582  
583 0 my $comments = $self->{'_hData'}->{'class'}->{$sFullClass}->{'comments'};
584 0 ▶ if (defined $comments) { print "$comments\n"; }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $comments) 0 0 0
585
586 0 print "\@nosubgrouping */\n";
587  
588 #if (defined $parent) { print "class $sFullClass : public $parent { \n"; }
589 #else { print "class $sFullClass { \n"; }
590 0 ▶ print "namespace $parent {\n" if ($parent);
Branch: 1 branch
BranchTrueFalseTotal
if $parent 0 0 0
591 0 print "class $class";
592 0 ▶ if (@{$classDef->{inherits}})
Branch: 1 branch
BranchTrueFalseTotal
if (@{$classDef->{"inherits"};}) 0 0 0
593 {
594 0 my $count = 0;
595 0 foreach my $inherit (@{$classDef->{inherits}})
596 {
597 0 ▶ if (defined($inherit))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $inherit) 0 0 0
598 {
599 0 ▶ print(($count++ == 0 ? ": " : ", ")." public ::".$inherit);
Branch: 1 branch
BranchTrueFalseTotal
$count++ == 0 ? : 0 0 0
600 }
601  
602 }
603 }
604 0 print "\n{\n";
605 0 print "public:\n";
606 }
607  
608 sub _PrintMethodBlock
609 0 ▶{
Subroutine _PrintMethodBlock: not called CC=10 SCAR=47.0
610 #** @method private _PrintMethodBlock ($class, $methodDef)
611 # This method will print the various subroutines/functions/methods in apprporiate doxygen syntax
612 # @param class - required string (name of the class)
613 # @param methodDef - required string (name of method)
614 #*
615 0 my $self = shift;
616 0 my $class = shift;
617 0 my $method = shift;
618
619 0 my $methodDef = $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method};
620  
621 0 my $state = $methodDef->{state};
622 0 my $type = $methodDef->{type};
623
624 0 my $logger = $self->GetLogger($self);
625 0 $logger->debug("### Entering _PrintMethodBlock ###");
626  
627 0 ▶ my $returntype = $methodDef->{'returntype'} || $type;
Condition0%0/3
$methodDef->{'returntype'} || $type
l!l&&r!l&&!r
000
MC/DC0%0/2
$methodDef->{'returntype'} || $type
$methodDef->{'returntype'} $type
Truth table0%0/3
A || B
A= $methodDef->{'returntype'}B= $type
ABresult
1X1
011
000
628 0 ▶ my $parameters = $methodDef->{'parameters'} || "";
Condition0%0/2
$methodDef->{'parameters'} || ''
l!l
00
MC/DC0%0/1
$methodDef->{'parameters'} || ''
$methodDef->{'parameters'}
Truth table0%0/2
A
A= $methodDef->{'parameters'}
Aresult
11
00
629 0 ▶ my $prototype = $methodDef->{'prototype'} || "";
Condition0%0/2
$methodDef->{'prototype'} || ''
l!l
00
MC/DC0%0/1
$methodDef->{'prototype'} || ''
$methodDef->{'prototype'}
Truth table0%0/2
A
A= $methodDef->{'prototype'}
Aresult
11
00
630  
631 0 ▶ if ($parameters =~ /^ *$/)
Branch: 1 branch
BranchTrueFalseTotal
if ($parameters =~ /^ *$/) { } 0 0 0
632 {
633 0 ▶ if ($prototype =~ /^ *$/)
Branch: 1 branch
BranchTrueFalseTotal
if ($prototype =~ /^ *$/) { } 0 0 0
634 {
635 0 print "/** \@fn $state $returntype $method\(\)\n";
636 }
637 else
638 {
639 0 print "/** \@fn $state $returntype $method\($prototype\)\n";
640 }
641 }
642 else
643 {
644 0 print "/** \@fn $state $returntype $method\($parameters\)\n";
645 }
646  
647 0 my $details = $methodDef->{'details'};
648 0 ▶ if (defined $details) { print "$details\n"; }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $details) { } 0 0 0
649 0 else { print "Undocumented Method\n"; }
650  
651 0 my $comments = $methodDef->{'comments'};
652 0 ▶ if (defined $comments) { print "$comments\n"; }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $comments) 0 0 0
653  
654 # Print collapsible source code block
655 0 print "\@htmlonly[block]\n";
656 0 print "<div id='codesection-$method' class='dynheader closed' style='cursor:pointer;' onclick='return toggleVisibility(this)'>\n";
657 0 print "\t<img id='codesection-$method-trigger' src='closed.png' alt='open/close icon' style='display:inline'/> <b>Code:</b>\n";
658 0 print "</div>\n";
659 0 print "<div id='codesection-$method-summary' class='dyncontent' style='display:block;font-size:small;'>click to view</div>\n";
660 0 print "<div id='codesection-$method-content' class='dyncontent' style='display: none;'>\n";
661 0 print "\@endhtmlonly\n";
662
663 0 print "\@code\n";
664 0 print "\# Number of lines of code in $method: $methodDef->{'length'}\n";
665 0 print "$methodDef->{'code'}\n";
666 0 print "\@endcode \@htmlonly[block]\n";
667 0 print "</div>\n";
668 0 print "\@endhtmlonly */\n";
669  
670 0 ▶ if ($parameters =~ /^ *$/)
Branch: 1 branch
BranchTrueFalseTotal
if ($parameters =~ /^ *$/) { } 0 0 0
671 {
672 0 ▶ if ($prototype =~ /^ *$/)
Branch: 1 branch
BranchTrueFalseTotal
if ($prototype =~ /^ *$/) { } 0 0 0
673 {
674 0 print "$state $returntype $method\(\)\;\n";
675 }
676 else
677 {
678 0 print "$state $returntype $method\($prototype\)\;\n";
679 }
680 }
681 else
682 {
683 0 print "$state $returntype $method\($parameters\)\;\n";
684 }
685 }
686  
687 sub _ProcessPerlMethod
688 0 ▶{
Subroutine _ProcessPerlMethod: not called CC=16 SCAR=56.1
689 #** @method private _ProcessPerlMethod ($line)
690 # This method will process the contents of a subroutine/function/method and try to figure out
691 # the name and whether or not it is a private or public method. The private or public status,
692 # if not defined in a doxygen comment block will be determined based on the file name. As with
693 # C and other languages, an "_" should be the first character for all private functions/methods.
694 # @param line - required string (full line of code)
695 #*
696 0 my $self = shift;
697 0 my $line = shift;
698 0 my $logger = $self->GetLogger($self);
699 0 $logger->debug("### Entering _ProcessPerlMethod ###");
700
701 0 my $sClassName = $self->{'_sCurrentClass'};
702  
703 0 ▶ if ($line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/)
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/) 0 0 0
Condition0%0/3
$line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/
!ll&&!rl&&r
000
MC/DC0%0/2
$line =~ /^\s*sub\s+([\w]+)/ and $line =~ /^\s*sub\s+([\D][\w]*)/
$line =~ /^\s*sub\s+([\w]+)/ $line =~ /^\s*sub\s+([\D][\w]*)/
Truth table0%0/3
A and B
A= $line =~ /^\s*sub\s+([\w]+)/B= $line =~ /^\s*sub\s+([\D][\w]*)/
ABresult
0X0
100
111
704 {
705 # We should keep track of the order in which the methods were written in the code so we can print
706 # them out in the same order
707 0 my $sName = $1;
708 # If they have declared the subrountine with a brace on the same line, lets remove it
709 0 $sName =~ s/\{.*\}?//;
710 # Remove any leading or trailing whitespace from the name, just to be safe
711 0 $sName =~ s/\s//g;
712 # check if we have a prototype
713 0 my ($method, $proto) = split /[()]/, $sName;
714 0 ▶ $sName = $method || "";
Condition0%0/2
$method || ''
l!l
00
MC/DC0%0/1
$method || ''
$method
Truth table0%0/2
A
A= $method
Aresult
11
00
715 0 $sName =~ s/\s//g;
716 0 ▶ if (defined($proto)) {$proto =~ s/\s//g;}
Branch: 1 branch
BranchTrueFalseTotal
if (defined $proto) 0 0 0
717 0 ▶ my $sProtoType = $proto || "";
Condition0%0/2
$proto || ''
l!l
00
MC/DC0%0/1
$proto || ''
$proto
Truth table0%0/2
A
A= $proto
Aresult
11
00
718 0 $logger->debug("Method Name: $sName");
719
720 0 push (@{$self->{'_hData'}->{'class'}->{$sClassName}->{'subroutineorder'}}, $sName);
721 0 $self->{'_sCurrentMethodName'} = $sName;
722 0 $self->{'_sProtoType'} = $self->_ConvertParameters($sProtoType);
723 }
724 0 ▶ if (!defined($self->{'_sCurrentMethodName'})) {$self->{'_sCurrentMethodName'}='';}
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_sCurrentMethodName"}) 0 0 0
725 0 ▶ if (!defined($self->{'_sProtoType'})) {$self->{'_sProtoType'}='';}
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_sProtoType"}) 0 0 0
726  
727 0 my $sMethodName = $self->{'_sCurrentMethodName'};
728 0 my $sProtoType = $self->{'_sProtoType'};
729
730 # Lets find out if this is a public or private method/function based on a naming standard
731 0 ▶ if ($sMethodName =~ /^_/) { $self->{'_sCurrentMethodState'} = 'private'; }
Branch: 1 branch
BranchTrueFalseTotal
if ($sMethodName =~ /^_/) { } 0 0 0
732 0 else { $self->{'_sCurrentMethodState'} = 'public'; }
733
734 0 my $sMethodState = $self->{'_sCurrentMethodState'};
735 0 $logger->debug("Method State: $sMethodState");
736
737 # We need to count the number of open and close braces so we can see if we are still in a subroutine or not
738 # but we need to becareful so that we do not count braces in comments and braces that are in match patters /\{/
739 # If there are more open then closed, then we are still in a subroutine
740 0 my $cleanline = $line;
741 0 $logger->debug("Cleanline: $cleanline");
742
743 # Remove any comments even those inline with code but not if the hash mark "#" is in a pattern match
744 # unless ($cleanline =~ /=~/) { $cleanline =~ s/#.*$//; }
745 # Patch from Stefan Tauner to address hash marks showing up at the last element of an array, $#array
746 0 ▶ unless ($cleanline =~ /=~/) { $cleanline =~ s/([^\$])#.*$/$1/; }
Branch: 1 branch
BranchTrueFalseTotal
unless ($cleanline =~ /=~/) 0 0 0
747 0 $logger->debug("Cleanline: $cleanline");
748 # Need to remove braces from counting when they are in a pattern match but not when they are supposed to be
749 # there as in the second use case listed below. Below the use cases is some ideas on how to do this.
750 # use case: $a =~ /\{/
751 # use case: if (/\{/) { foo; }
752 # use case: unless ($cleanline =~ /=~/) { $cleanline =~ s/#.*$//; }
753 0 $cleanline =~ s#/.*?/##g;
754 0 $logger->debug("Cleanline: $cleanline");
755 # Remove any braces found in a print statement lile:
756 # use case: print "some foo { bar somethingelse";
757 # use case: print "$self->{'_hData'}->{'filename'}->{'details'}\n";
758 0 ▶ if ($cleanline =~ /(.*?print\s*)(.*?);(.*)/)
Branch: 1 branch
BranchTrueFalseTotal
if ($cleanline =~ /(.*?print\s*)(.*?);(.*)/) 0 0 0
759 {
760 0 my $sLineData1 = $1;
761 0 my $sLineData2 = $2;
762 0 my $sLineData3 = $3;
763 0 $sLineData2 =~ s#[{}]##g;
764 0 $cleanline = $sLineData1 . $sLineData2. $sLineData3;
765 }
766 #$cleanline =~ s/(print\s*\".*){(.*\")/$1$2/g;
767 0 $logger->debug("Cleanline: $cleanline");
768
769 0 $self->{'_iOpenBrace'} += @{[$cleanline =~ /\{/g]};
770 0 $self->{'_iCloseBrace'} += @{[$cleanline =~ /\}/g]};
771 0 $logger->debug("Open Brace Number: $self->{'_iOpenBrace'}");
772 0 $logger->debug("Close Brace Number: $self->{'_iCloseBrace'}");
773
774
775 # Use Case 1: sub foo { return; }
776 # Use Case 2: sub foo {\n}
777 # Use Case 3: sub foo \n {\n }
778  
779 0 ▶ if ($self->{'_iOpenBrace'} > $self->{'_iCloseBrace'})
Branch: 2 branches
BranchTrueFalseTotal
if ($self->{'_iOpenBrace'} > $self->{'_iCloseBrace'}) { } 0 0 0
elsif ($self->{'_iOpenBrace'} > 0 and $self->{'_iOpenBrace'} == $self->{'_iCloseBrace'}) { } 0 0 0
780 {
781 # Use Case 2, still in subroutine
782 0 $logger->debug("We are still in the subroutine");
783 }
784 ▶ elsif ($self->{'_iOpenBrace'} > 0 && $self->{'_iOpenBrace'} == $self->{'_iCloseBrace'})
Condition0%0/3
$self->{"_iOpenBrace"} > 0 and $self->{"_iOpenBrace"} == $self->{"_iCloseBrace"}
!ll&&!rl&&r
000
MC/DC0%0/2
$self->{"_iOpenBrace"} > 0 and $self->{"_iOpenBrace"} == $self->{"_iCloseBrace"}
$self->{"_iOpenBrace"} > 0 $self->{"_iOpenBrace"} == $self->{"_iCloseBrace"}
Truth table0%0/3
A and B
A= $self->{"_iOpenBrace"} > 0B= $self->{"_iOpenBrace"} == $self->{"_iCloseBrace"}
ABresult
0X0
100
111
785 {
786 # Use Case 1, we are leaving a subroutine
787 0 $logger->debug("We are leaving the subroutine");
788 0 $self->_ChangeState('NORMAL');
789 0 $self->RESETSUB();
790 }
791 else
792 {
793 # Use Case 3, still in subroutine
794 0 $logger->debug("A subroutine has been started but we are not yet in it as we have yet to see an open brace");
795 }
796  
797 # Doxygen makes use of the `@` symbol and treats it as a special reserved character. This is a problem for perl
798 # and especially when we are documenting our own Doxygen code we have print statements that include things like `@endcode`
799 # as is found in _PrintMethodBlock(). Lets convert those `@` to `@amp;`
800 0 $line =~ s/\@endcode/\&\#64\;endcode/g;
801  
802 # Record the current line for code output
803 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'code'} .= $line;
804 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'length'}++;
805
806 # Only set these values if they were not already set by a comment block outside the subroutine
807 # This is for public/private
808 0 ▶ unless (defined $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'state'})
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_hData"}{"class"}{$sClassName}{"subroutines"}{$sMethodName}{"state"}) 0 0 0
809 {
810 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'state'} = $sMethodState;
811 }
812 # This is for function/method
813 0 ▶ unless (defined $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'type'})
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_hData"}{"class"}{$sClassName}{"subroutines"}{$sMethodName}{"type"}) 0 0 0
814 {
815 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'type'} = "method";
816 }
817 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'prototype'} = $sProtoType;
818 }
819  
820 sub _ProcessPodCommentBlock
821 0 ▶{
Subroutine _ProcessPodCommentBlock: not called CC=2 SCAR=17.9
822 #** @method private _ProcessPodCommentBlock ()
823 # This method will process an entire POD block in one pass, after it has all been gathered by the state machine.
824 #*
825 0 my $self = shift;
826 0 my $logger = $self->GetLogger($self);
827 0 $logger->debug("### Entering _ProcessPodCommentBlock ###");
828
829 0 my $sClassName = $self->{'_sCurrentClass'};
830 0 my @aBlock = @{$self->{'_aPodBlock'}};
831
832 # Lets clean up the array in the object now that we have a local copy as we will no longer need that. We want to make
833 # sure it is all clean and ready for the next comment block
834 0 $self->RESETPOD();
835  
836 0 my $sPodRawText;
837 0 foreach (@aBlock)
838 {
839 # If we find any Doxygen special characters in the POD, lets escape them
840 0 s/(\@|\\|\%|#)/\\$1/g;
841 0 $sPodRawText .= $_;
842 }
843  
844 0 my $parser = new Pod::POM();
845 0 my $pom = $parser->parse_text($sPodRawText);
846 0 Doxygen::Filter::Perl::POD->setAsLabel($self->{'_hData'}->{'filename'}->{'fullpath'});
847 0 my $sPodParsedText = Doxygen::Filter::Perl::POD->print($pom);
848  
849 0 $sPodParsedText =~ s/\*\/\*/\\*\&zwj;\/\\*/g;
850 0 $sPodParsedText =~ s/\/\*/\/\&zwj;\\*/g;
851 0 $sPodParsedText =~ s/\*\//\\*\&zwj;\//g;
852 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'comments'} .= $sPodParsedText;
853 }
854  
855  
856 sub _ProcessDoxygenCommentBlock
857 0 ▶{
Subroutine _ProcessDoxygenCommentBlock: not called CC=36 SCAR=71.9
858 #** @method private _ProcessDoxygenCommentBlock ()
859 # This method will process an entire comment block in one pass, after it has all been gathered by the state machine
860 #*
861 0 my $self = shift;
862 0 my $logger = $self->GetLogger($self);
863 0 $logger->debug("### Entering _ProcessDoxygenCommentBlock ###");
864
865 0 my @aBlock = @{$self->{'_aDoxygenBlock'}};
866
867 # Lets clean up the array in the object now that we have a local copy as we will no longer need that. We want to make
868 # sure it is all clean and ready for the next comment block
869 0 $self->RESETDOXY();
870  
871 0 my $sClassName = $self->{'_sCurrentClass'};
872 0 my $sSubState = '';
873 0 $logger->debug("We are currently in class $sClassName");
874
875 # Lets grab the command line and put it in a variable for easier use
876 0 my $sCommandLine = $aBlock[0];
877 0 $logger->debug("The command line for this doxygen comment is $sCommandLine");
878  
879 0 $sCommandLine =~ /^\s*#\*\*\s+\@([\w:]+)\s+(.*)/;
880 0 my $sCommand = lc($1);
881 0 my $sOptions = $2;
882 0 ▶ if (!defined($sOptions))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $sOptions) 0 0 0
883 {
884 # Lets check special case with a '.' or ',' e.g @winchhooks.
885 0 $sCommandLine =~ /^\s*#\*\*\s+\@([\w:]+)([\.,].*)/;
886 0 $sCommand = lc($1);
887 0 $sOptions = "";
888 0 ▶ if (defined($2))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $2) 0 0 0
889 {
890 0 $sOptions = "$2";
891 }
892 }
893 0 $logger->debug("Command: $sCommand");
894 0 $logger->debug("Options: $sOptions");
895  
896 # If the user entered @fn instead of @function, lets change it
897 0 ▶ if ($sCommand eq "fn") { $sCommand = "function"; }
Branch: 1 branch
BranchTrueFalseTotal
if ($sCommand eq "fn") 0 0 0
898
899 # Lets find out what doxygen sub state we should be in
900 0 ▶ if ($sCommand eq 'file') { $sSubState = 'DOXYFILE'; }
Branch: 7 branches
BranchTrueFalseTotal
if ($sCommand eq 'file') { } 0 0 0
elsif ($sCommand eq 'class') { } 0 0 0
elsif ($sCommand eq 'package') { } 0 0 0
elsif ($sCommand eq 'function') { } 0 0 0
elsif ($sCommand eq 'method') { } 0 0 0
elsif ($sCommand eq 'attr') { } 0 0 0
elsif ($sCommand eq 'var') { } 0 0 0
901 0 elsif ($sCommand eq 'class') { $sSubState = 'DOXYCLASS'; }
902 0 elsif ($sCommand eq 'package') { $sSubState = 'DOXYCLASS'; }
903 0 elsif ($sCommand eq 'function') { $sSubState = 'DOXYFUNCTION'; }
904 0 elsif ($sCommand eq 'method') { $sSubState = 'DOXYMETHOD'; }
905 0 elsif ($sCommand eq 'attr') { $sSubState = 'DOXYATTR'; }
906 0 elsif ($sCommand eq 'var') { $sSubState = 'DOXYATTR'; }
907 0 else { $sSubState = 'DOXYCOMMENT'; }
908 0 $logger->debug("Substate is now $sSubState");
909  
910 0 ▶ if ($sSubState eq 'DOXYFILE' )
Branch: 5 branches
BranchTrueFalseTotal
if ($sSubState eq 'DOXYFILE') { } 0 0 0
elsif ($sSubState eq 'DOXYCLASS') { } 0 0 0
elsif ($sSubState eq 'DOXYCOMMENT') { } 0 0 0
elsif ($sSubState eq 'DOXYATTR') { } 0 0 0
elsif ($sSubState eq 'DOXYFUNCTION' or $sSubState eq 'DOXYMETHOD') { } 0 0 0
911 {
912 0 $logger->debug("Processing a Doxygen file object");
913 # We need to remove the command line from this block
914 0 shift @aBlock;
915 0 $self->{'_hData'}->{'filename'}->{'details'} = $self->_RemovePerlCommentFlags(\@aBlock);
916 }
917 elsif ($sSubState eq 'DOXYCLASS')
918 {
919 0 $logger->debug("Processing a Doxygen class object");
920 #my $sClassName = $sOptions;
921 0 ▶ my $sClassName = $sOptions || $sClassName;
Condition0%0/3
$sOptions || $sClassName
l!l&&r!l&&!r
000
MC/DC0%0/2
$sOptions || $sClassName
$sOptions $sClassName
Truth table0%0/3
A || B
A= $sOptionsB= $sClassName
ABresult
1X1
011
000
922 0 my $classDef = $self->_SwitchClass($sClassName);
923 # We need to remove the command line from this block
924 0 shift @aBlock;
925 #$self->{'_hData'}->{'class'}->{$sClassName}->{'details'} = $self->_RemovePerlCommentFlags(\@aBlock);
926 0 $classDef->{'details'} = $self->_RemovePerlCommentFlags(\@aBlock);
927 }
928 elsif ($sSubState eq 'DOXYCOMMENT')
929 {
930 0 $logger->debug("Processing a Doxygen class object");
931 # For extra comment blocks we need to add the command and option line back to the front of the array
932 0 my $sMethodName = $self->{'_sCurrentMethodName'};
933 0 ▶ if (defined $sMethodName)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sMethodName) { } 0 0 0
934 {
935 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'comments'} .= "\n";
936 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'comments'} .= $self->_RemovePerlCommentFlags(\@aBlock);
937 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'comments'} .= "\n";
938 }
939 else
940 {
941 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'comments'} .= "\n";
942 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'comments'} .= $self->_RemovePerlCommentFlags(\@aBlock);
943 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'comments'} .= "\n";
944 }
945 }
946 elsif ($sSubState eq 'DOXYATTR')
947 {
948 # Process the doxygen header first then loop through the rest of the comments
949 #my ($sState, $sAttrName, $sComments) = ($sOptions =~ /(?:(public|private)\s+)?([\$@%\*][\w:]+)\s+(.*)/);
950 0 my ($sState, $modifiers, $modifiersLoop, $modifiersChoice, $fullSpec, $typeSpec, $typeName, $typeLoop, $pointerLoop, $typeCode, $sAttrName, $sComments) = ($sOptions =~ /(?:(public|protected|private)\s+)?(((static|const)\s+)*)((((\w+::)*\w+(\s+|\s*\*+\s+|\s+\*+\s*))|)([\$@%\*])([\w:]+))\s+(.*)/);
951 0 ▶ if (defined $sAttrName)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sAttrName) { } 0 0 0
952 {
953 0 ▶ my $attrDef = $self->{'_hData'}->{'class'}->{$sClassName}->{'attributes'}->{$sAttrName} ||= {};
Condition0%0/2
$self->{"_hData"}{"class"}{$sClassName}{"attributes"}{$sAttrName} ||= {}
l!l
00
MC/DC0%0/1
$self->{"_hData"}{"class"}{$sClassName}{"attributes"}{$sAttrName} ||= {}
$self->{"_hData"}{"class"}{$sClassName}{"attributes"}{$sAttrName}
Truth table0%0/2
A
A= $self->{"_hData"}{"class"}{$sClassName}{"attributes"}{$sAttrName}
Aresult
11
00
954 0 ▶ if ($typeName)
Branch: 1 branch
BranchTrueFalseTotal
if ($typeName) { } 0 0 0
955 {
956 0 $attrDef->{'type'} = $typeName;
957 }
958 else
959 {
960 0 $attrDef->{'type'} = $self->_ConvertTypeCode($typeCode);
961 }
962 0 ▶ if (defined $sState)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sState) 0 0 0
963 {
964 0 $attrDef->{'state'} = $sState;
965 }
966 0 ▶ if (defined $sComments)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sComments) 0 0 0
967 {
968 0 $attrDef->{'comments'} = $sComments;
969 }
970 0 ▶ if (defined $modifiers)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $modifiers) 0 0 0
971 {
972 0 $attrDef->{'modifiers'} = $modifiers;
973 }
974 ## We need to remove the command line from this block
975 0 shift @aBlock;
976 0 $attrDef->{'details'} = $self->_RemovePerlCommentFlags(\@aBlock);
977 0 push(@{$self->GetCurrentClass()->{attributeorder}}, $sAttrName);
978 }
979 else
980 {
981 0 $self->ReportError("invalid syntax for attribute: $sOptions\n");
982 }
983 } # End DOXYATTR
984 ▶ elsif ($sSubState eq 'DOXYFUNCTION' || $sSubState eq 'DOXYMETHOD')
Condition0%0/3
$sSubState eq "DOXYFUNCTION" or $sSubState eq "DOXYMETHOD"
l!l&&r!l&&!r
000
MC/DC0%0/2
$sSubState eq "DOXYFUNCTION" or $sSubState eq "DOXYMETHOD"
$sSubState eq "DOXYFUNCTION" $sSubState eq "DOXYMETHOD"
Truth table0%0/3
A or B
A= $sSubState eq "DOXYFUNCTION"B= $sSubState eq "DOXYMETHOD"
ABresult
1X1
011
000
985 {
986 # Process the doxygen header first then loop through the rest of the comments
987 0 $sOptions =~ /^(.*?)\s*\(\s*(.*?)\s*\)/;
988 0 $sOptions = $1;
989 0 my $sParameters = $2;
990  
991 0 my @aOptions;
992 my $state;
993 0 my $sMethodName;
994
995 0 ▶ if (defined $sOptions)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sOptions) 0 0 0
996 {
997 0 @aOptions = split(/\s+/, $sOptions);
998 # State = Public/Private
999 0 ▶ if ($aOptions[0] eq "public" || $aOptions[0] eq "private" || $aOptions[0] eq "protected")
Branch: 1 branch
BranchTrueFalseTotal
if ($aOptions[0] eq "public" or $aOptions[0] eq "private" or $aOptions[0] eq "protected") 0 0 0
Condition0%0/6
$aOptions[0] eq "public" or $aOptions[0] eq "private" or $aOptions[0] eq "protected"
l!l&&r!l&&!r
000
$aOptions[0] eq "public" or $aOptions[0] eq "private"
l!l&&r!l&&!r
000
MC/DC0%0/3
$aOptions[0] eq "public" or $aOptions[0] eq "private" or $aOptions[0] eq "protected"
$aOptions[0] eq "public" $aOptions[0] eq "private" $aOptions[0] eq "protected"
Truth table0%0/4
A or B or C
A= $aOptions[0] eq "public"B= $aOptions[0] eq "private"C= $aOptions[0] eq "protected"
ABCresult
1XX1
01X1
0011
0000
1000 {
1001 0 $state = shift @aOptions;
1002 }
1003 0 $sMethodName = pop(@aOptions);
1004 }
1005  
1006 0 ▶ if ($sSubState eq "DOXYFUNCTION" && !grep(/^static$/, @aOptions))
Branch: 1 branch
BranchTrueFalseTotal
if ($sSubState eq "DOXYFUNCTION" and not grep(/^static$/, @aOptions)) 0 0 0
Condition0%0/3
$sSubState eq "DOXYFUNCTION" and not grep(/^static$/, @aOptions)
!ll&&!rl&&r
000
MC/DC0%0/2
$sSubState eq "DOXYFUNCTION" and not grep(/^static$/, @aOptions)
$sSubState eq "DOXYFUNCTION" not grep(/^static$/, @aOptions)
Truth table0%0/3
A and not(B)
A= $sSubState eq "DOXYFUNCTION"B= not grep(/^static$/, @aOptions)
ABresult
0X0
100
111
1007 {
1008 0 unshift(@aOptions, "static");
1009 }
1010  
1011 0 ▶ unless (defined $sMethodName)
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $sMethodName) 0 0 0
1012 {
1013 # If we are already in a subroutine and a user uses sloppy documentation and only does
1014 # #**@method in side the subroutine, then lets pull the current method name from the object.
1015 # If there is no method defined there, we should die.
1016 0 ▶ if (defined $self->{'_sCurrentMethodName'}) { $sMethodName = $self->{'_sCurrentMethodName'}; }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{'_sCurrentMethodName'}) { } 0 0 0
1017 0 else { die "Missing method name in $sCommand syntax"; }
1018 }
1019  
1020 # If we are not yet in a subroutine, lets keep track that we are now processing a subroutine and its name
1021 0 ▶ unless (defined $self->{'_sCurrentMethodName'}) { $self->{'_sCurrentMethodName'} = $sMethodName; }
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_sCurrentMethodName"}) 0 0 0
1022  
1023 0 ▶ if (defined $sParameters) { $sParameters = $self->_ConvertParameters($sParameters); }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $sParameters) 0 0 0
1024
1025 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'returntype'} = join(" ", @aOptions);
1026 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'type'} = $sCommand;
1027 0 ▶ if (defined $state)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $state) 0 0 0
1028 {
1029 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'state'} = $state;
1030 }
1031 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'parameters'} = $sParameters;
1032 # We need to remove the command line from this block
1033 0 shift @aBlock;
1034 0 $self->{'_hData'}->{'class'}->{$sClassName}->{'subroutines'}->{$sMethodName}->{'details'} = $self->_RemovePerlCommentFlags(\@aBlock);
1035  
1036 } # End DOXYFUNCTION || DOXYMETHOD
1037 }
1038  
1039 sub _RemovePerlCommentFlags
1040 0 ▶{
Subroutine _RemovePerlCommentFlags: not called CC=6 SCAR=37.4
1041 #** @method private _RemovePerlCommentFlags ($aBlock)
1042 # This method will remove all of the comment marks "#" for our output to Doxygen. If the line is
1043 # flagged for verbatim then lets not do anything.
1044 # @param aBlock - required array_ref (doxygen comment as an array of code lines)
1045 # @retval sBlockDetails - string (doxygen comments in one long string)
1046 #*
1047 0 my $self = shift;
1048 0 my $aBlock = shift;
1049 0 my $logger = $self->GetLogger($self);
1050 0 $logger->debug("### Entering _RemovePerlCommentFlags ###");
1051
1052 0 my $sBlockDetails = "";
1053 0 my $iInVerbatimBlock = 0;
1054 0 foreach my $line (@$aBlock)
1055 {
1056 # Lets check for a verbatim command option like '# @verbatim'
1057 0 ▶ if ($line =~ /^\s*#\s*\@verbatim/)
Branch: 2 branches
BranchTrueFalseTotal
if ($line =~ /^\s*#\s*\@verbatim/) { } 0 0 0
elsif ($line =~ /^\s*#\s*\@endverbatim/) { } 0 0 0
1058 {
1059 0 $logger->debug("Found verbatim command");
1060 # We need to remove the comment marker from the '# @verbaim' line now since it will not be caught later
1061 0 $line =~ s/^\s*#\s*/ /;
1062 0 $iInVerbatimBlock = 1;
1063 }
1064 elsif ($line =~ /^\s*#\s*\@endverbatim/)
1065 {
1066 0 $logger->debug("Found endverbatim command");
1067 0 $iInVerbatimBlock = 0;
1068 }
1069 # Lets remove any doxygen command initiator
1070 0 $line =~ s/^\s*#\*\*\s*//;
1071 # Lets remove any doxygen command terminators
1072 0 $line =~ s/^\s*#\*\s*//;
1073 # Lets remove all of the Perl comment markers so long as we are not in a verbatim block
1074 # if ($iInVerbatimBlock == 0) { $line =~ s/^\s*#+//; }
1075 # Patch from Sebastian Rose to address spacing and indentation in code examples
1076 0 ▶ if ($iInVerbatimBlock == 0) { $line =~ s/^\s*#\s?//; }
Branch: 1 branch
BranchTrueFalseTotal
if ($iInVerbatimBlock == 0) 0 0 0
1077 0 $logger->debug("code: $line");
1078 # Patch from Mihai MOJE to address method comments all on the same line.
1079 0 $sBlockDetails .= $line . "<br>";
1080 #$sBlockDetails .= $line;
1081 }
1082 0 $sBlockDetails =~ s/^([ \t]*\n)+//s;
1083 0 chomp($sBlockDetails);
1084 0 ▶ if ($sBlockDetails)
Branch: 1 branch
BranchTrueFalseTotal
if ($sBlockDetails) 0 0 0
1085 {
1086 0 $sBlockDetails =~ s/^/ \*/gm;
1087 0 $sBlockDetails .= "\n";
1088 }
1089 0 return $sBlockDetails;
1090 }
1091  
1092 sub _ConvertToOfficialDoxygenSyntax
1093 7 ▶{
Subroutine _ConvertToOfficialDoxygenSyntax: called CC=2 SCAR=7.1
1094 #** @method private _ConvertToOfficialDoxygenSyntax ($line)
1095 # This method will check the current line for various unsupported doxygen comment blocks and convert them
1096 # to the type we support, #** @command. The reason for this is so that we do not need to add them in
1097 # every if statement throughout the code.
1098 # @param line - required string (line of code)
1099 # @retval line - string (line of code)
1100 #*
1101 7 my $self = shift;
1102 7 my $line = shift;
1103 7 my $logger = $self->GetLogger($self);
1104 7 $logger->debug("### Entering _ConvertToOfficialDoxygenSyntax ###");
1105  
1106 # This will match ## @command and convert it to #** @command
1107 0 ▶ if ($line =~ /^\s*##\s+\@/) { $line =~ s/^(\s*)##(\s+\@)/$1#\*\*$2/; }
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^\s*##\s+\@/) { } 0 7 7
1108 else {
1109 7 $logger->debug('Nothing to do, did not find any ## @');
1110 }
1111 7 return $line;
1112 }
1113  
1114 sub _ConvertTypeCode
1115 0 ▶{
Subroutine _ConvertTypeCode: not called CC=1 SCAR=6.9
1116 #** @method private _ConvertTypeCode($code)
1117 # This method will change the $, @, and %, etc to written names so that Doxygen does not have a problem with them
1118 # @param code
1119 # required prefix of variable
1120 #*
1121 0 my $self = shift;
1122 0 my $code = shift;
1123 0 my $logger = $self->GetLogger($self);
1124 0 $logger->debug("### Entering _ConvertParameters ###");
1125  
1126 # Lets clean up the parameters list so that it will work with Doxygen
1127 0 $code =~ s/\*/any_type /g;
1128 0 $code =~ s/\$\$/scalar_ref/g;
1129 0 $code =~ s/\@\$/array_ref/g;
1130 0 $code =~ s/\%\$/hash_ref/g;
1131 0 $code =~ s/\$/scalar/g;
1132 0 $code =~ s/\&/subroutine/g;
1133 0 $code =~ s/\@/array/g;
1134 0 $code =~ s/\%/hash/g;
1135
1136 0 return $code;
1137 }
1138  
1139 sub _ConvertParameters
1140 0 ▶{
Subroutine _ConvertParameters: not called CC=1 SCAR=6.9
1141 #** @method private _ConvertParameters ()
1142 # This method will change the $, @, and %, etc to written names so that Doxygen does not have a problem with them
1143 # @param sParameters - required string (variable parameter to change)
1144 #*
1145 0 my $self = shift;
1146 0 my $sParameters = shift;
1147 0 my $logger = $self->GetLogger($self);
1148 0 $logger->debug("### Entering _ConvertParameters ###");
1149  
1150 # Lets clean up the parameters list so that it will work with Doxygen
1151 0 $sParameters =~ s/\*/any_type /g;
1152 0 $sParameters =~ s/\$\$/scalar_ref /g;
1153 0 $sParameters =~ s/\@\$/array_ref /g;
1154 0 $sParameters =~ s/\%\$/hash_ref /g;
1155 0 $sParameters =~ s/\$/scalar /g;
1156 0 $sParameters =~ s/\&/subroutine /g;
1157 0 $sParameters =~ s/\@/array /g;
1158 0 $sParameters =~ s/\%/hash /g;
1159
1160 0 return $sParameters;
1161 }
1162  
1163 =head1 NAME
1164  
1165 Doxygen::Filter::Perl - A perl code pre-filter for Doxygen
1166  
1167 =head1 DESCRIPTION
1168  
1169 The Doxygen::Filter::Perl module is designed to provide support for documenting
1170 perl scripts and modules to be used with the Doxygen engine. We plan on
1171 supporting most Doxygen style comments and POD (plain old documentation) style
1172 comments. The Doxgyen style comment blocks for methods/functions can be inside
1173 or outside the method/function. Doxygen::Filter::Perl is hosted at
1174 http://perldoxygen.sourceforge.net/
1175  
1176 =head1 USAGE
1177  
1178 Install Doxygen::Filter::Perl via CPAN or from source. If you install from
1179 source then do:
1180  
1181 perl Makefile.PL
1182 make
1183 make install
1184
1185 Make sure that the doxygen-filter-perl script was copied from this project into
1186 your path somewhere and that it has RX permissions. Example:
1187  
1188 /usr/local/bin/doxygen-filter-perl
1189  
1190 Copy over the Doxyfile file from this project into the root directory of your
1191 project so that it is at the same level as your lib directory. This file will
1192 have all of the presets needed for documenting Perl code. You can edit this
1193 file with the doxywizard tool if you so desire or if you need to change the
1194 lib directory location or the output location (the default output is ./doc).
1195 Please see the Doxygen manual for information on how to configure the Doxyfile
1196 via a text editor or with the doxywizard tool.
1197 Example:
1198  
1199 /home/jordan/workspace/PerlDoxygen/trunk/Doxyfile
1200 /home/jordan/workspace/PerlDoxygen/trunk/lib/Doxygen/Filter/Perl.pm
1201  
1202 Once you have done this you can simply run the following from the root of your
1203 project to document your Perl scripts or methods. Example:
1204  
1205 /home/jordan/workspace/PerlDoxygen/trunk/> doxygen Doxyfile
1206  
1207 All of your documentation will be in the ./doc/html/ directory inside of your
1208 project root.
1209  
1210 =head1 DOXYGEN SUPPORT
1211  
1212 The following Doxygen style comment is the preferred block style, though others
1213 are supported and are listed below:
1214  
1215 #**
1216 # ........
1217 #*
1218  
1219 You can also start comment blocks with "##" and end comment blocks with a blank
1220 line or real code, this allows you to place comments right next to the
1221 subroutines that they refer to if you wish. A comment block must have
1222 continuous "#" comment markers as a blank line can be used as a termination
1223 mark for the doxygen comment block.
1224  
1225 In other languages the Doxygen @fn structural indicator is used to document
1226 subroutines/functions/methods and the parsing engine figures out what is what.
1227 In Perl that is a lot harder to do so I have added a `@method` and `@function`
1228 structural indicator so that they can be documented separately.
1229  
1230 =head2 Supported Structural Indicators
1231  
1232 #** @file [filename]
1233 # ........
1234 #*
1235
1236 #** @class [class name (ex. Doxygen::Filter::Perl)]
1237 # ........
1238 #*
1239
1240 #** @method or @function [public|protected|private] [method-name] (parameters)
1241 # ........
1242 #*
1243  
1244 #** @attr or @var [public|protected|private] [type] {$%@}[attribute-name] [brief description]
1245 # ........
1246 #*
1247
1248 #** @section [section-name] [section-title]
1249 # ........
1250 #*
1251
1252 #** @brief [notes]
1253 # ........
1254 #*
1255  
1256 =head2 Support Style Options and Section Indicators
1257
1258 All doxygen style options and section indicators are supported inside the
1259 structural indicators that we currently support.
1260  
1261 =head2 Documenting Subroutines/Functions/Methods
1262  
1263 The Doxygen style comment blocks that describe a function or method can
1264 exist before, after, or inside the subroutine that it is describing. Examples
1265 are listed below. It is also important to note that you can leave the public/private
1266 out and the filter will guess based on the subroutine name. The normal convention
1267 in other languages like C is to have the function/method start with an "_" if it
1268 is private/protected. We do the same thing here even though there is really no
1269 such thing in Perl. The whole reason for this is to help users of the code know
1270 what functions they should call directly and which they should not. The generic
1271 documentation blocks for functions and methods look like:
1272  
1273 #** @function [public|protected|private] [return-type] function-name (parameters)
1274 # @brief A brief description of the function
1275 #
1276 # A detailed description of the function
1277 # @params value [required|optional] [details]
1278 # @retval value [details]
1279 # ....
1280 #*
1281  
1282 #** @method [public|protected|private] [return-type] method-name (parameters)
1283 # @brief A brief description of the method
1284 #
1285 # A detailed description of the method
1286 # @params value [required|optional] [details]
1287 # @retval value [details]
1288 # ....
1289 #*
1290  
1291 The parameters would normally be something like $foo, @bar, or %foobar. I have
1292 also added support for scalar, array, and hash references and those would be
1293 documented as $$foo, @$bar, %$foobar. An example would look this:
1294  
1295 #** @method public ProcessDataValues ($$sFile, %$hDataValues)
1296  
1297 =head2 Function / Method Example
1298  
1299 sub test1
1300 {
1301 #** @method public test1 ($value)
1302 # ....
1303 #*
1304 }
1305  
1306 #** @method public test2 ($value)
1307 # ....
1308 #*
1309 sub test2
1310 {
1311
1312 }
1313  
1314 =head1 DATA STRUCTURE
1315  
1316 $self->{'_hData'}->{'filename'}->{'fullpath'} = string
1317 $self->{'_hData'}->{'filename'}->{'shortname'} = string
1318 $self->{'_hData'}->{'filename'}->{'version'} = string
1319 $self->{'_hData'}->{'filename'}->{'details'} = string
1320 $self->{'_hData'}->{'includes'} = array
1321  
1322 $self->{'_hData'}->{'class'}->{'classorder'} = array
1323 $self->{'_hData'}->{'class'}->{$class}->{'subroutineorder'} = array
1324 $self->{'_hData'}->{'class'}->{$class}->{'attributeorder'} = array
1325 $self->{'_hData'}->{'class'}->{$class}->{'details'} = string
1326 $self->{'_hData'}->{'class'}->{$class}->{'comments'} = string
1327  
1328 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'type'} = string (method / function)
1329 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'returntype'} = string (return type)
1330 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'state'} = string (public / private)
1331 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'parameters'} = string (method / function parameters)
1332 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'prototype'} = string (method / function prototype parameters)
1333 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'code'} = string
1334 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'length'} = integer
1335 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'details'} = string
1336 $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'comments'} = string
1337  
1338 $self->{'_hData'}->{'class'}->{$class}->{'attributes'}->{$variable}->{'state'} = string (public / private)
1339 $self->{'_hData'}->{'class'}->{$class}->{'attributes'}->{$variable}->{'modifiers'} = string
1340 $self->{'_hData'}->{'class'}->{$class}->{'attributes'}->{$variable}->{'comments'} = string
1341 $self->{'_hData'}->{'class'}->{$class}->{'attributes'}->{$variable}->{'details'} = string
1342  
1343 =head1 AUTHOR
1344  
1345 Bret Jordan <jordan at open1x littledot org> or <jordan2175 at gmail littledot com>
1346  
1347 =head1 LICENSE
1348  
1349 Doxygen::Filter::Perl is licensed with an Apache 2 license. See the LICENSE
1350 file for more details.
1351  
1352 =cut
1353  
1354 1 return 1;
↑ Summary Filter/Perl/POD.pm »