/ 
Java-Doc-20171014
River stage zero No dependents
/ Java::Doc

Name

Java::Doc - Extract documentation from Java source code

Synopsis

use Java::Doc;

my $j = Java::Doc::new;                                # New document builder

$j->source = [qw(~/java/layoutText/LayoutText.java)];  # Source files
$j->target =  qq(~/java/documentation.html);           # Output html
$j->indent = 20;                                       # Indentation
$j->colors = [map {"#$_"} qw(ccFFFF FFccFF FFFFcc),    # Background colours
                          qw(CCccFF FFCCcc ccFFCC)];
$j->html;                                              # Create html

Each source file is parsed for documentation information which is then collated into a colorful cross referenced html file.

Documentation is extracted for packages, classes, methods.

Packages

Lines matching

package packageName ;

are assumed to define packages.

Classes

Lines with comments //C are assumed to define classes:

class className    //C <comment>

with the text of the comment being the definition of the class.

Classes are terminated with:

} //C className

which allows class document definitions to be nested.

Methods

Methods are specified by lines with comments matching //M:

methodName ()  //M <comment>

methodName     //M <comment>

with the description of the method contained in the text of the comment extending to the end of the line.

Constructors should be marked with comments matching //c as in:

methodName     //c <comment>

Methods that are overridden should be noted with a comment as in:

methodName     //O=package.class.method <comment>

Parameters

Methods that are not overrides and that do have parameters should place the parameters declarations one per line on succeeding lines marked with comments //P as in:

parameterName //P <comment>

Example

The following fragment of java code provides an example of documentation held as comments that can be processed by this module:

package com.appaapps;

public class Outer        //C Layout text on a canvas
 {public static void draw //M Draw text to fill a fractional area of the canvas
   (final Canvas canvas)  //P Canvas to draw on
   {}

  class Inner              //C Inner class
   {InnerText()            //c Constructor
     {}
   } //C Inner
 } //C Outer

Description

The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.

Attributes

Attributes that can be set or retrieved by assignment

source :lvalue

A reference to an array of Java source files that contain documentation as well as java

target :lvalue

Name of the file to contain the generated documentation

wellKnownClasses :lvalue

A reference to an array of urls that contain the class name of well known Java classes such as: TreeMap which will be used in place of the class name to make it possible to locate definitions of these other classes.

indent :lvalue

Indentation for methods vs classes and classes vs packages - defaults to 0

colors :lvalue

A reference to an array of colours expressed in html format - defaults to white - the background applied to each output section is cycled through these colours to individuate each section.

Methods

Methods available

new()

Create a new java doc processor

html($)

Create documentation using html as the output format. Write the generated html to the file specified by target if any and return the generated html as an array of lines.

1  $javaDoc  Java doc processor

Index

1 colors

2 html

3 indent

4 new

5 source

6 target

7 wellKnownClasses

Installation

This module is written in 100% Pure Perl and, thus, it is easy to read, use, modify and install.

Standard Module::Build process for building and installing modules:

perl Build.PL
./Build
./Build test
./Build install

Author

philiprbrenan@gmail.com

http://www.appaapps.com

Copyright

Copyright (c) 2016-2017 Philip R Brenan.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.