| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 56 | 1 | ▶ | say STDERR $fileOrString unless $snf; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 70 | 0 | "at line $line in file/string:\n$fileOrString\n$_\n"; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 71 | 30 | }->(); | |||||||||||||||||||||||||||||||||||||||||||||||||
| 72 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 73 | 30 | ▶ | if ($state == 0) | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 74 | 18 | ▶ | {if (m(\A\s*package\s+((\w+|\.)+))) # 'package' package ; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 4 branches
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 96 | 0 | ▶ | my $n = $a->{name} cmp $b->{name}; return $n if $n; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 118 | 0 | {push @attributes, q(constructor); # Constructor | |||||||||||||||||||||||||||||||||||||||||||||||||
| 119 | 0 | ▶ | if ($package and $class) | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 3 branches
Condition0%0/3
$package and $class
MC/DC0%0/2
$package and $class
$package
$class
Truth table0%0/3
A and B
A= $packageB= $class
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition33%1/3
$package and $class
MC/DC0%0/2
$package and $class
$package
$class
Truth table33%1/3
A and B
A= $packageB= $class
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition33%1/3
$empty or $override
MC/DC0%0/2
$empty or $override
$empty
$override
Truth table33%1/3
A or B
A= $emptyB= $override
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 146 | 0 | ▶ | warn "$m class $at" unless $class; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition33%2/6
$package and $class and $method
$package and $class
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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 162 | 3 | {my $m = $parse->{$package}{$class}{methods}[-1]; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 163 | 3 | ▶ | if (my $p = $m->{parameters}) | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 164 | 3 | ▶ | {if (my @p = @$p) | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
MC/DC0%0/1
$javaDoc->indent // 0
$javaDoc->indent
Truth table50%1/2
A
A= $javaDoc->indent
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 202 | 1 | my @c = @{$javaDoc->colors}; # Back ground colours | |||||||||||||||||||||||||||||||||||||||||||||||||
| 203 | 1 | ▶ | @c = 'white' unless @c; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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"} // []
MC/DC0%0/1
$method{"attributes"} // []
$method{"attributes"}
Truth table50%1/2
A
A= $method{"attributes"}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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"
MC/DC0%0/1
$method{"typeSig"} // "void"
$method{"typeSig"}
Truth table50%1/2
A
A= $method{"typeSig"}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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"} // ""
MC/DC0%0/1
$method{"typeSig"} // ""
$method{"typeSig"}
Truth table50%1/2
A
A= $method{"typeSig"}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 // []
MC/DC0%0/1
$attributes // []
$attributes
Truth table50%1/2
A
A= $attributes
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 586 | 1 | my $s = eval "join('', <${p}::DATA>)"; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 587 | 1 | ▶ | $@ and die $@; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 588 | 1 | ▶ | eval $s; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 589 | 1 | ▶ | $@ and die $@; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 590 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 591 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 592 | 1 | ▶ | test unless caller; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 593 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 594 | 1 | 1; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 595 | # podDocumentation | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 596 | __DATA__ | ||||||||||||||||||||||||||||||||||||||||||||||||||