blib/lib/Java/Doc.pm

filter: Statementstmt 85.7% 181 / 211 Branchbran 43.4% 33 / 76 Conditioncond 36.0% 9 / 25 MC/DCmcdc 0.0% 0 / 14 Subroutinesub 100% 17 / 17 Podpod 22.2% 2 / 9 totaltotal 68.7% 242 / 352 CC 61 SCAR 45.4
CC
61
Cov
71%
parseJavaFile
197.8
htmlJavaFiles
16.1
test
5.2
CRAP 94.1
↑ Summary
1 #!/usr/bin/perl
2 #-------------------------------------------------------------------------------
3 # Extract documentation from Java source code.
4 # Philip R Brenan at gmail dot com, Appa Apps Ltd, 2017
5 #-------------------------------------------------------------------------------
6 # Override when we click on the method it should go to the overridden method and the comment can then be shortened
7 # Method should use a hash of fields, it currently uses an array
8 # returns in title should link to definition of that item
9 # class in title should link to definition of that class
10 package Java::Doc;
11 1 require v5.16.0;
12 1 ▶use warnings FATAL => qw(all);
Subroutine BEGIN: called CC=1 SCAR=0.0
13 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 1 ▶use Carp qw(confess);
Subroutine BEGIN: called CC=1 SCAR=0.0
15 1 ▶use Data::Dump qw(dump);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 1 ▶use Data::Table::Text qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 1 our $VERSION = '20171014';
19  
20 1 genLValueHashMethods(qw(parse)); # Combined parse tree of all the input files read
21 1 genLValueHashMethods(qw(classes)); # Classes encountered in all the input files read
22  
23 1 my %veryWellKnownClassesHash = map {$_=>1} split /\n/, &veryWellKnownClasses; # Urls describing some well known Java classes
24  
25 sub urlIfKnown($$) # Replace a well known type with an informative url
26 12 ▶ {my ($javaDoc, $type) = @_; # Java doc builder, type to replace with an informative url
Subroutine urlIfKnown: called CC=3 SCAR=11.0
Pod undocumented
27 12 for my $url(keys %veryWellKnownClassesHash, @{$javaDoc->wellKnownClasses})
28 264 {my $i = index($url, "/$type.html");
29 264 ▶ if ($i >= 0)
Branch: 1 branch
BranchTrueFalseTotal
if ($i >= 0) 6 258 264
30 6 {return qq(<a target="_blank" href="$url">$type</a>);
31 }
32 }
33 $type
34 6 }
35  
36 sub getAttributes($) # Get the attributes from a method type: public, private, final, static etc
37 12 ▶ {my ($type) = @_; # Type as parsed out
Subroutine getAttributes: called CC=3 SCAR=11.0
Pod undocumented
38 12 my $t = qq( $type ); # Blank pad
39 12 $t =~ s(\A\s*[\(\{]) ( )gs; # Replace leading open bracket with space
40 12 my @attributes; # Method attributes
41 12 for(qw(public private protected abstract final static))
42 72 ▶ {push @attributes, $_ if $t =~ m($_)s;
Branch: 1 branch
BranchTrueFalseTotal
if $t =~ /$_/s 12 60 72
43 72 $t =~ s($_) ( )gs;
44 }
45 12 $t =~ s(\s+) ( )gs; # Remove excess white space
46 12 (trim($t), @attributes)
47 }
48 #say STDERR dump([getAttributes(" (final public static float ")]); exit;
49  
50 sub parseJavaFile($$) # Parse java file for package, class, method, parameters
51 1 ▶ {my ($javaDoc, $fileOrString) = @_; # Java doc builder, Parse tree, java file or string of java to process
Subroutine parseJavaFile: called CC=35 SCAR=52.9
Pod undocumented
52 1 my $parse = $javaDoc->parse; # Parse tree
53  
54 1 my $snf = $fileOrString =~ m(\n)s; # String not file
55 1 ▶ my $s = $fileOrString =~ m(\n)s ? $fileOrString : readFile($fileOrString); # Source
Branch: 1 branch
BranchTrueFalseTotal
$fileOrString =~ /\n/s ? : 1 0 1
56 1 ▶ say STDERR $fileOrString unless $snf;
Branch: 1 branch
BranchTrueFalseTotal
unless $snf 0 1 1
57  
58 1 my $package; # Package we are in
59 my @class; # Containing classes as array
60 1 my $class; # Containing classes as a.b.c
61 1 my $method; # Method we are in
62 1 my $state = 0; # 0 - outer, 1 - parameters to last method
63  
64 1 my $line = 0; # Line numbers
65 1 for(split /\n/, $s)
66 30 {++$line;
67  
68 my $at = sub # Position
69 30 ▶ {return "at line: $line\n$_\n" if $snf;
Subroutine __ANON__: called CC=2 SCAR=9.2
Branch: 1 branch
BranchTrueFalseTotal
if $snf 30 0 30
70 0 "at line $line in file/string:\n$fileOrString\n$_\n";
71 30 }->();
72  
73 30 ▶ if ($state == 0)
Branch: 2 branches
BranchTrueFalseTotal
if ($state == 0) { } 18 12 30
elsif ($state == 1) { } 12 0 12
74 18 ▶ {if (m(\A\s*package\s+((\w+|\.)+))) # 'package' package ;
Branch: 4 branches
BranchTrueFalseTotal
if (/\A\s*package\s+((\w+|\.)+)/) { } 1 17 18
elsif (m[\A.*?class\s+(\S+)\s*\{?\s*//C\s+(.*?)\s*\Z]) { } 2 15 17
elsif (m[\A\s*}\s*//C\s+(\S+)]) { } 0 15 15
elsif (m[\A\s*(.*?) \s+(\w+) \s*(\x28\s*\x29\s*(?:\x7b\s*\x7d)?)? \s*\x28?\s* //(M|c|O=\S+)\s+(.*?)\s*\Z]x) { } 3 12 15
75 {#say STDERR "Package = $1";
76 1 $package = $1;
77 }
78 elsif (m(\A.*?class\s+(\S+)\s*\{?\s*//C\s+(.*?)\s*\Z)) # Class with optional '{' //C
79 2 {push @class, $1; # Save containing class
80 2 $class = join '.', @class;
81 #say STDERR "Class $class = $1 = $2";
82 2 $javaDoc->classes->{$class} = $parse->{$package}{$class}{comment} = $2; # Record the last encountered class as the class to link to - could be improved!
83 }
84 elsif (m(\A\s*}\s*//C\s+(\S+))) # '}' '//C' className - close class className
85 {#say STDERR "Class = $1 End";
86 0 ▶ if (!@class)
Branch: 2 branches
BranchTrueFalseTotal
if (not @class) { } 0 0 0
elsif ($1 ne $class[-1]) { } 0 0 0
87 0 {warn "Closing class $1 but no class to close $at";
88 }
89 elsif ($1 ne $class[-1])
90 0 {warn "Closing class $1 but in class $class $at";
91 }
92 else
93 {$parse->{$package}{$class}{methods} =
94 [sort
95 0 ▶ {my $r = $b->{res} cmp $a->{res}; return $r if $r;
Branch: 1 branch
BranchTrueFalseTotal
if $r 0 0 0
96 0 ▶ my $n = $a->{name} cmp $b->{name}; return $n if $n;
Branch: 1 branch
BranchTrueFalseTotal
if $n 0 0 0
97 0 my $c = $a->{comment} cmp $b->{comment}; return $c;
98 }
99 0 @{$parse->{$package}{$class}{methods}}];
100  
101 0 pop @class;
102 0 $class = join '.', @class;
103 }
104 }
105 elsif # Method with either '()' meaning no parameters or optional '(' followed by //M for method, //c for constructor, //O=package.method for override of the named method. If () is specified then {} can follow to indicate an empty method
106 (m(\A\s*(.*?)
107 \s+(\w+)
108 \s*(\x28\s*\x29\s*(?:\x7b\s*\x7d)?)?
109 \s*\x28?\s*
110 //(M|c|O=\S+)\s+(.*?)\s*\Z)x) # Comment
111 3 {my ($empty, $res, $comment) = ($3, $4, $5);
112 3 $method = $2;
113  
114 3 my ($type, @attributes) = getAttributes($1); # Method attributes
115  
116 3 my $override; # Method is an override
117 3 ▶ if ($res =~ m(\Ac\Z)s) # In summa it is a constructor
Branch: 2 branches
BranchTrueFalseTotal
if ($res =~ /\Ac\Z/s) { } 0 3 3
elsif ($res =~ /\AO=(.+?)\Z/s) { } 0 3 3
118 0 {push @attributes, q(constructor); # Constructor
119 0 ▶ if ($package and $class)
Branch: 3 branches
BranchTrueFalseTotal
if ($package and $class) { } 0 0 0
elsif (not $package) { } 0 0 0
elsif (not $class) { } 0 0 0
Condition0%0/3
$package and $class
!ll&&!rl&&r
000
MC/DC0%0/2
$package and $class
$package $class
Truth table0%0/3
A and B
A= $packageB= $class
ABresult
0X0
100
111
120 0 {$type = qq(<a href="#$package.$class.$method">$method</a>); # Type for a constructor is the constructor name
121 }
122 elsif (!$package)
123 0 {warn "Ignoring method $method because no package specified $at";
124 }
125 elsif (!$class)
126 0 {warn "Ignoring method $method because no containing class $at";
127 }
128 }
129 elsif ($res =~ m(\AO=(.+?)\Z)s) # Override
130 0 {$override = $1;
131 0 ▶ my $dot = $comment =~ m(\.\Z)s ? '' : '.';
Branch: 1 branch
BranchTrueFalseTotal
$comment =~ /\.\Z/s ? : 0 0 0
132 0 $comment = qq($comment$dot Overrides: <a href="#$override">$override</a>);
133 }
134  
135 3 ▶ if ($package and $class) # Save method details is possible
Branch: 1 branch
BranchTrueFalseTotal
if ($package and $class) { } 3 0 3
Condition33%1/3
$package and $class
!ll&&!rl&&r
003
MC/DC0%0/2
$package and $class
$package $class
Truth table33%1/3
A and B
A= $packageB= $class
ABresult
0X0
100
111
136 {#say STDERR "Method = $method == $type == $comment ";
137  
138 3 push @{$parse->{$package}{$class}{methods}},
139 {type=>$javaDoc->urlIfKnown($type), name=>$method, res=>$res,
140 comment=>$comment, attributes=>[@attributes], line=>$line};
141 3 ▶ $state = 1 if !$empty and !$override; # Get parameters next if method has parameters and is not an override
Branch: 1 branch
BranchTrueFalseTotal
unless $empty or $override 3 0 3
Condition33%1/3
$empty or $override
l!l&&r!l&&!r
003
MC/DC0%0/2
$empty or $override
$empty $override
Truth table33%1/3
A or B
A= $emptyB= $override
ABresult
1X1
011
000
142 }
143 else
144 0 {my $m = qq(Ignoring method $method as no preceding);
145 0 ▶ warn "$m package $at" unless $package;
Branch: 1 branch
BranchTrueFalseTotal
unless $package 0 0 0
146 0 ▶ warn "$m class $at" unless $class;
Branch: 1 branch
BranchTrueFalseTotal
unless $class 0 0 0
147 }
148 }
149 }
150 elsif ($state == 1)
151 12 ▶ {if (m(\A.\s*(.+?)\s+(\w+)\s*[,\)\{]*\s*//P\s+(.*?)\s*\Z)) # type name, optional ',){', //P
Branch: 1 branch
BranchTrueFalseTotal
if (m[\A.\s*(.+?)\s+(\w+)\s*[,\)\{]*\s*//P\s+(.*?)\s*\Z]) { } 9 3 12
152 {#say STDERR "Parameter =$1=$2=$3";
153 9 my ($type, $parameter, $comment) = ($1, $2, $3);
154 9 my ($t, @attributes) = getAttributes($type);
155 9 push @{$parse->{$package}{$class}{methods}[-1]{parameters}},
156 [$javaDoc->urlIfKnown($t), $parameter, $comment, [@attributes],
157 $line];
158 }
159 else # End of parameters if the line does not match
160 3 {$state = 0;
161 3 ▶ if ($package and $class and $method)
Branch: 3 branches
BranchTrueFalseTotal
if ($package and $class and $method) { } 3 0 3
elsif (not $package) { } 0 0 0
elsif (not $class) { } 0 0 0
Condition33%2/6
$package and $class and $method
!ll&&!rl&&r
003
$package and $class
!ll&&!rl&&r
003
MC/DC0%0/3
$package and $class and $method
$package $class $method
Truth table25%1/4
A and B and C
A= $packageB= $classC= $method
ABCresult
0XX0
10X0
1100
1111
162 3 {my $m = $parse->{$package}{$class}{methods}[-1];
163 3 ▶ if (my $p = $m->{parameters})
Branch: 1 branch
BranchTrueFalseTotal
if (my $p = $m->{"parameters"}) 3 0 3
164 3 ▶ {if (my @p = @$p)
Branch: 1 branch
BranchTrueFalseTotal
if (my(@p) = @$p) 3 0 3
165 3 {$m->{nameSig} = join ', ', map {$_->[1]} @p;
166 3 $m->{typeSig} = join ', ', map {$_->[0]} @p;
167 }
168 }
169 }
170 elsif (!$package)
171 0 {warn "Ignoring method $method because no package specified $at";
172 }
173 elsif (!$class)
174 0 {warn "Ignoring method $method because no containing class $at";
175 }
176 }
177 }
178 }
179 1 if (0 and @class)
180 {if ($snf)
181 {warn "Classes still to close at end of string: ".join(' ', @class);
182 }
183 else
184 {warn "Classes still to close: ".join(' ', @class). "\n".
185 "At end of file:\n$fileOrString";
186 }
187 }
188 $parse
189 1 }
190  
191 sub parseJavaFiles($) # Parse all the input files into one parse tree
192 1 ▶ {my ($javaDoc) = @_; # Java doc processor
Subroutine parseJavaFiles: called CC=2 SCAR=6.9
Pod undocumented
193 1 for(sort @{$javaDoc->source}) # Extend the parse tree with the parse of each source file
194 1 {$javaDoc->parseJavaFile($_);
195 }
196 }
197  
198 sub htmlJavaFiles($) # Create documentation using html for all java files from combined parse tree
199 1 ▶ {my ($javaDoc) = @_; # Java doc processor, combined parse tree
Subroutine htmlJavaFiles: called CC=16 SCAR=27.8
Pod undocumented
200 1 my $parse = $javaDoc->parse; # Parse tree
201 1 ▶ my $indent = $javaDoc->indent // 0; # Indentation per level
Condition50%1/2
$javaDoc->indent // 0
l!l
01
MC/DC0%0/1
$javaDoc->indent // 0
$javaDoc->indent
Truth table50%1/2
A
A= $javaDoc->indent
Aresult
11
00
202 1 my @c = @{$javaDoc->colors}; # Back ground colours
203 1 ▶ @c = 'white' unless @c;
Branch: 1 branch
BranchTrueFalseTotal
unless @c 0 1 1
204 1 my $d; # Current background colour - start
205 1 my $D = q(</div>); # Current background colour - end
206 my $swapColours = sub # Swap background colour
207 7 ▶ {my ($margin) = @_;
Subroutine __ANON__: called CC=1 SCAR=0.0
208 7 my $m = $margin * $indent;
209 7 push @c, my $c = shift @c;
210 7 $d = qq(<div style="background-color: $c; margin-left: $m">);
211 1 };
212 1 &$swapColours(0); # Swap background colour
213  
214 1 my @h = <<END;
215 $d
216 <head>
217 <meta charset="UTF-8">
218 </head>
219 <body>
220 <h1>Packages</h1>
221 <table border="1" cellspacing="20">
222 END
223 1 for my $package(sort keys %$parse)
224 1 {push @h, qq(<tr><td><a href="#$package">$package</a></tr>);
225 }
226 1 push @h, <<END;
227 </table>
228 $D
229 END
230  
231 1 for my $package(sort keys %$parse)
232 1 {my %package = %{$parse->{$package}};
233 1 &$swapColours(1);
234 1 push @h, <<END;
235 <a name="$package"/>
236 $d
237 <h2>Package: <big>$package</big></h2>
238 <table border="1" cellspacing="20">
239 <tr><th>Class<th>Description</tr>
240 END
241 1 for my $class(sort keys %package)
242 2 {my %class = %{$package{$class}};
243 2 my $classComment = $class{comment};
244 2 push @h, <<"END";
245 <tr><td><a href="#$package/$class">$class</a>
246 <td>$classComment
247 </tr>
248 END
249 }
250 1 push @h, <<END;
251 </table>
252 $D
253 END
254 1 for my $class(sort keys %package)
255 2 {my %class = %{$package{$class}};
256 2 my $classComment = $class{comment};
257 2 &$swapColours(2);
258 2 push @h, <<END;
259 $d
260 <a name="$package/$class"/>
261 <h3>Class: <big>$class</big>, package: $package</h3>
262 <p>$classComment
263 <table border="1" cellspacing="20">
264 <tr><th>Returns<th>Method<th>Signature<th>Attributes<th>Line<th>Description</tr>
265 END
266 2 for my $method(@{$class{methods}})
267 3 {my %method = %{$method};
268 3 ▶ my $attr = join ' ', @{$method{attributes}//[]};
Condition50%1/2
$method{"attributes"} // []
l!l
30
MC/DC0%0/1
$method{"attributes"} // []
$method{"attributes"}
Truth table50%1/2
A
A= $method{"attributes"}
Aresult
11
00
269 3 my $type = $method{type};
270 3 my $name = $method{name};
271 3 my $comment = $method{comment};
272 3 my $line = $method{line};
273 3 ▶ my $sig = $method{typeSig} // 'void';
Condition50%1/2
$method{"typeSig"} // "void"
l!l
30
MC/DC0%0/1
$method{"typeSig"} // "void"
$method{"typeSig"}
Truth table50%1/2
A
A= $method{"typeSig"}
Aresult
11
00
274 3 push @h, <<END;
275 <tr><td>$type
276 <td><a href="#$package/$class/$name">$name</a>
277 <td>$sig
278 <td>$attr
279 <td>$line
280 <td>$comment
281 </tr>
282 END
283 }
284 2 push @h, <<END;
285 </table>
286 $D
287 END
288 2 for my $method(@{$class{methods}})
289 3 {my %method = %{$method};
290 3 my $type = $method{type};
291 3 my $name = $method{name};
292 3 my $comment = $method{comment};
293 3 ▶ my $sig = $method{typeSig} // '';
Condition50%1/2
$method{"typeSig"} // ""
l!l
30
MC/DC0%0/1
$method{"typeSig"} // ""
$method{"typeSig"}
Truth table50%1/2
A
A= $method{"typeSig"}
Aresult
11
00
294 3 &$swapColours(3);
295 3 push @h, <<END;
296 $d
297 <a name="$package/$class/$name"/>
298 <h4><big>$name($sig)</big> returns <big>$type</big> <small>in class $class</small></h4>
299 <p>$comment</p>
300 END
301  
302 3 ▶ if (my $parameters = $method{parameters})
Branch: 1 branch
BranchTrueFalseTotal
if (my $parameters = $method{"parameters"}) 3 0 3
303 3 {my @parameters = @$parameters;
304 3 push @h, <<END;
305 <table border="1" cellspacing="20">
306 <tr><th>Name<th>Type<th>Line<th>Description</tr>
307 END
308 3 for my $parameter(@parameters)
309 9 {my ($type, $name, $comment, $attributes, $line) = @$parameter;
310 9 ▶ my $attr = join ' ', @{$attributes//[]};
Condition50%1/2
$attributes // []
l!l
90
MC/DC0%0/1
$attributes // []
$attributes
Truth table50%1/2
A
A= $attributes
Aresult
11
00
311 9 push @h, qq(<tr><td>$name<td>$type<td>$line<td>$comment</tr>);
312 }
313 3 push @h, <<END;
314 </table>
315 END
316 }
317 3 push @h, <<END;
318 $D
319 </body>
320 END
321 }
322 }
323 }
324  
325 1 s(L<(.+?)>) (<a href="#$1">$1</a>)gs for @h;
326  
327 @h
328 1 }
329  
330 1 ▶sub veryWellKnownClasses {<<'END'}
Subroutine veryWellKnownClasses: called CC=1 SCAR=0.0
Pod undocumented
331 https://developer.android.com/reference/android/app/Activity.html
332 https://developer.android.com/reference/android/content/Context.html
333 https://developer.android.com/reference/android/graphics/BitmapFactory.html
334 https://developer.android.com/reference/android/graphics/Bitmap.html
335 https://developer.android.com/reference/android/graphics/Canvas.html
336 https://developer.android.com/reference/android/graphics/drawable/BitmapDrawable.html
337 https://developer.android.com/reference/android/graphics/drawable/Drawable.html
338 https://developer.android.com/reference/android/graphics/Matrix.html
339 https://developer.android.com/reference/android/graphics/Paint.html
340 https://developer.android.com/reference/android/graphics/Path.html
341 https://developer.android.com/reference/android/graphics/PorterDuff.Mode.html
342 https://developer.android.com/reference/android/graphics/RectF.html
343 https://developer.android.com/reference/android/media/MediaPlayer.html
344 https://developer.android.com/reference/android/util/DisplayMetrics.html
345 https://developer.android.com/reference/java/io/ByteArrayOutputStream.html
346 https://developer.android.com/reference/java/io/DataInputStream.html
347 https://developer.android.com/reference/java/io/DataOutputStream.html
348 https://developer.android.com/reference/java/io/File.html
349 https://developer.android.com/reference/java/io/FileOutputStream.html
350 https://developer.android.com/reference/java/lang/String.html
351 https://developer.android.com/reference/java/lang/Thread.html
352 https://developer.android.com/reference/java/util/Stack.html
353 https://developer.android.com/reference/java/util/TreeMap.html
354 https://developer.android.com/reference/java/util/TreeSet.html
355 https://developer.android.com/studio/command-line/adb.html
356 END
357  
358 #1 Attributes # Attributes that can be set or retrieved by assignment
359  
360 1 if (1) { # Parameters that can be set by the caller
361 1 genLValueArrayMethods(qw(source)); # A reference to an array of Java source files that contain documentation as well as java
362 1 genLValueScalarMethods(qw(target)); # Name of the file to contain the generated documentation
363 1 genLValueArrayMethods(qw(wellKnownClasses)); # A reference to an array of urls that contain the class name of well known Java classes such as: L<TreeMap|/https://developer.android.com/reference/java/util/TreeMap.html> which will be used in place of the class name to make it possible to locate definitions of these other classes.
364 1 genLValueScalarMethods(qw(indent)); # Indentation for methods vs classes and classes vs packages - defaults to 0
365 1 genLValueArrayMethods(qw(colors)); # A reference to an array of colours expressed in html format - defaults to B<white> - the background applied to each output section is cycled through these colours to individuate each section.
366 }
367  
368 #1 Methods # Methods available
369  
370 sub new # Create a new java doc processor
371 1 ▶ {bless {}; # Java doc processor
Subroutine new: called CC=1 SCAR=0.0
Pod documented
372 }
373  
374 sub html($) # Create documentation using html as the output format. Write the generated html to the file specified by L<target|/target> if any and return the generated html as an array of lines.
375 1 ▶ {my ($javaDoc) = @_; # Java doc processor
Subroutine html: called CC=2 SCAR=8.1
Pod documented
376 1 $javaDoc->parseJavaFiles; # Parse the input files
377 1 my @h = $javaDoc->htmlJavaFiles; # Write as html
378  
379 1 ▶ if (my $file = $javaDoc->target)
Branch: 1 branch
BranchTrueFalseTotal
if (my $file = $javaDoc->target) 0 1 1
380 0 {my $h = @h;
381 0 writeFile($file, join "\n", @h);
382 0 say STDERR "$h lines of documentation written to:\n$file";
383 }
384 @h # Return the generated html
385 1 }
386  
387 # podDocumentation
388  
389 =encoding utf-8
390  
391 =head1 Name
392  
393 Java::Doc - Extract L<documentation|https://metacpan.org/source/PRBRENAN/Java-Doc-20171012/examples/documentation.html>
394 from L<Java source code|https://metacpan.org/source/PRBRENAN/Java-Doc-20171012/examples/documentation.java>
395  
396 =head1 Synopsis
397  
398 use Java::Doc;
399  
400 my $j = Java::Doc::new; # New document builder
401  
402 $j->source = [qw(~/java/layoutText/LayoutText.java)]; # Source files
403 $j->target = qq(~/java/documentation.html); # Output html
404 $j->indent = 20; # Indentation
405 $j->colors = [map {"#$_"} qw(ccFFFF FFccFF FFFFcc), # Background colours
406 qw(CCccFF FFCCcc ccFFCC)];
407 $j->html; # Create html
408  
409 Each source file is parsed for documentation information which is then
410 collated into a colorful cross referenced html file.
411  
412 Documentation is extracted for L<packages|/Packages>, L<classes|/Classes>,
413 L<methods|/Methods>.
414  
415 =head2 Packages
416  
417 Lines matching
418  
419 package packageName ;
420  
421 are assumed to define packages.
422  
423 =head2 Classes
424  
425 Lines with comments B<//C> are assumed to define classes:
426  
427 class className //C <comment>
428  
429 with the text of the comment being the definition of the class.
430  
431 Classes are terminated with:
432  
433 } //C className
434  
435 which allows class document definitions to be nested.
436  
437 =head2 Methods
438  
439 Methods are specified by lines with comments matching B<//M>:
440  
441 methodName () //M <comment>
442  
443 methodName //M <comment>
444  
445 with the description of the method contained in the text of the comment
446 extending to the end of the line.
447  
448 Constructors should be marked with comments matching B<//c> as in:
449  
450 methodName //c <comment>
451  
452 Methods that are overridden should be noted with a comment as in:
453  
454 methodName //O=package.class.method <comment>
455  
456 =head2 Parameters
457  
458 Methods that are not overrides and that do have parameters should place the
459 parameters declarations one per line on succeeding lines marked with comments
460 B<//P> as in:
461  
462 parameterName //P <comment>
463  
464 =head2 Example
465  
466 The following fragment of java code provides an example of documentation held as
467 comments that can be processed by this module:
468  
469 package com.appaapps;
470  
471 public class Outer //C Layout text on a canvas
472 {public static void draw //M Draw text to fill a fractional area of the canvas
473 (final Canvas canvas) //P Canvas to draw on
474 {}
475  
476 class Inner //C Inner class
477 {InnerText() //c Constructor
478 {}
479 } //C Inner
480 } //C Outer
481  
482 =head1 Description
483  
484 The following sections describe the methods in each functional area of this
485 module. For an alphabetic listing of all methods by name see L<Index|/Index>.
486  
487  
488  
489 =head1 Attributes
490  
491 Attributes that can be set or retrieved by assignment
492  
493 =head2 source :lvalue
494  
495 A reference to an array of Java source files that contain documentation as well as java
496  
497  
498 =head2 target :lvalue
499  
500 Name of the file to contain the generated documentation
501  
502  
503 =head2 wellKnownClasses :lvalue
504  
505 A reference to an array of urls that contain the class name of well known Java classes such as: L<TreeMap|/https://developer.android.com/reference/java/util/TreeMap.html> which will be used in place of the class name to make it possible to locate definitions of these other classes.
506  
507  
508 =head2 indent :lvalue
509  
510 Indentation for methods vs classes and classes vs packages - defaults to 0
511  
512  
513 =head2 colors :lvalue
514  
515 A reference to an array of colours expressed in html format - defaults to B<white> - the background applied to each output section is cycled through these colours to individuate each section.
516  
517  
518 =head1 Methods
519  
520 Methods available
521  
522 =head2 new()
523  
524 Create a new java doc processor
525  
526  
527 =head2 html($)
528  
529 Create documentation using html as the output format. Write the generated html to the file specified by L<target|/target> if any and return the generated html as an array of lines.
530  
531 1 $javaDoc Java doc processor
532  
533  
534 =head1 Index
535  
536  
537 1 L<colors|/colors>
538  
539 2 L<html|/html>
540  
541 3 L<indent|/indent>
542  
543 4 L<new|/new>
544  
545 5 L<source|/source>
546  
547 6 L<target|/target>
548  
549 7 L<wellKnownClasses|/wellKnownClasses>
550  
551 =head1 Installation
552  
553 This module is written in 100% Pure Perl and, thus, it is easy to read, use,
554 modify and install.
555  
556 Standard L<Module::Build> process for building and installing modules:
557  
558 perl Build.PL
559 ./Build
560 ./Build test
561 ./Build install
562  
563 =head1 Author
564  
565 L<philiprbrenan@gmail.com|mailto:philiprbrenan@gmail.com>
566  
567 L<http://www.appaapps.com|http://www.appaapps.com>
568  
569 =head1 Copyright
570  
571 Copyright (c) 2016-2017 Philip R Brenan.
572  
573 This module is free software. It may be used, redistributed and/or modified
574 under the same terms as Perl itself.
575  
576 =cut
577  
578  
579  
580 # Tests and documentation
581  
582 sub test
583 1 ▶ {my $p = __PACKAGE__;
Subroutine test: called CC=5 SCAR=16.4
Pod undocumented
584 1 binmode($_, ":utf8") for *STDOUT, *STDERR;
585 1 ▶ return if eval "eof(${p}::DATA)";
Branch: 1 branch
BranchTrueFalseTotal
if eval "eof(${p}::DATA)" 0 1 1
586 1 my $s = eval "join('', <${p}::DATA>)";
587 1 ▶ $@ and die $@;
Branch: 1 branch
BranchTrueFalseTotal
$@ and die $@ 0 1 1
588 1 ▶ eval $s;
Subroutine BEGIN: called CC=1 SCAR=0.0
589 1 ▶ $@ and die $@;
Branch: 1 branch
BranchTrueFalseTotal
$@ and die $@ 0 1 1
590 }
591  
592 1 ▶test unless caller;
Branch: 1 branch
BranchTrueFalseTotal
unless caller 0 1 1
593  
594 1 1;
595 # podDocumentation
596 __DATA__
↑ Summary