View on
Philip R Brenan > Java-Doc-20171012 > Java::Doc



Annotate this POD

View/Report Bugs
Module Version: 20171012   Source  

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/];  # 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.


Lines matching

  package packageName ;

are assumed to define packages.


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 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>


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>


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


Create a new java doc processor


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 test
  ./Build install

Author ^

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.

syntax highlighting: