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

Download:
Java-Doc-20171012.tar.gz

Dependencies

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

syntax highlighting: