doc.doclets
Class PtDoclet

java.lang.Object
  doc.doclets.PtDoclet

public class PtDoclet
extends java.lang.Object

Generate PtDoc output. See ptolemy/vergil/basic/DocML_1.dtd for the dtd.

If javadoc is called with -d directoryName, then documentation will be generated in directoryName. If the KEPLER property is set, then for a class named foo.bar.Baz, the generated file is named Baz.doc.xml. If the KEPLER property is not set, then the generated file is named foo/bar/Baz.xml.

This doclet writes the names of all the classes for which documentation was generated in a file called allNamedObjs.txt

Since:

Ptolemy II 5.2

Version:

$Id: PtDoclet.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Christopher Brooks, Edward A. Lee, Contributors: Nandita Mangal, Ian Brown

Field Summary

private static java.lang.String	_header Header string for XML PtDoc output.
private static java.lang.String	_outputDirectory Directory to which the output is to be written.

Constructor Summary

PtDoclet()

Method Summary

private static java.lang.String	_customTagCommentText(com.sun.javadoc.ProgramElementDoc programElementDoc) Process customTags and return text that contains links to the javadoc output.
private static java.lang.StringBuffer	_generateClassLevelDocumentation(com.sun.javadoc.ClassDoc classDoc) Generate the classLevel documentation for a class
private static java.lang.String	_generateFieldDocumentation(com.sun.javadoc.ClassDoc classDoc, java.lang.Class fieldBaseClass, java.lang.String element) Generate documentation for all fields that are derived from a specific base class.
private static java.lang.String	_getOutputDirectory(java.lang.String[][] options) Process the doclet command line arguments and return the value of the -d parameter, if any.
private static java.lang.String	_inlineTagCommentText(com.sun.javadoc.ProgramElementDoc programElementDoc) Process inlineTags and return text that contains links to the javadoc output.
private static java.lang.String	_relativizePath(java.lang.String baseDirectory, java.lang.String destinationClassName, com.sun.javadoc.ProgramElementDoc programElementDoc, boolean isIncluded) Given two dot separated classpath names, return a relative path to the corresponding doc file.
private static void	_writeDoc(java.lang.String className, java.lang.String documentation) Write the output to a file.
static int	optionLength(java.lang.String option) Given a command line option, return the number of command line arguments needed by that option.
static boolean	start(com.sun.javadoc.RootDoc root) Process the java files and generate PtDoc XML.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_outputDirectory

private static java.lang.String _outputDirectory

Directory to which the output is to be written.

_header

private static java.lang.String _header

Header string for XML PtDoc output.

Constructor Detail

PtDoclet

public PtDoclet()

Method Detail

optionLength

public static int optionLength(java.lang.String option)

Given a command line option, return the number of command line arguments needed by that option.

Parameters:

option - The command line option

Returns:

If the option is "-d", return 2; otherwise, return 0.

start

public static boolean start(com.sun.javadoc.RootDoc root)
                     throws java.io.IOException,
                            java.lang.ClassNotFoundException

Process the java files and generate PtDoc XML. Only classes that extend ptolemy.actor.TypedAtomicActor are processed, all other classes are ignored.

Parameters:

root - The root of the java doc tree.

Returns:

Always return true;

Throws:

java.io.IOException - If there is a problem writing the documentation.

java.lang.ClassNotFoundException - If there is a problem finding the class of one of the fields.

_customTagCommentText

private static java.lang.String _customTagCommentText(com.sun.javadoc.ProgramElementDoc programElementDoc)

Process customTags and return text that contains links to the javadoc output.

Parameters:

programElementDoc - The class for which we are generating documentation.

_inlineTagCommentText

private static java.lang.String _inlineTagCommentText(com.sun.javadoc.ProgramElementDoc programElementDoc)

Process inlineTags and return text that contains links to the javadoc output.

Parameters:

programElementDoc - The class for which we are generating documentation.

_generateClassLevelDocumentation

private static java.lang.StringBuffer _generateClassLevelDocumentation(com.sun.javadoc.ClassDoc classDoc)

Generate the classLevel documentation for a class

Parameters:

classDoc - The class for which we are generating documentation.

_generateFieldDocumentation

private static java.lang.String _generateFieldDocumentation(com.sun.javadoc.ClassDoc classDoc,
                                                            java.lang.Class fieldBaseClass,
                                                            java.lang.String element)
                                                     throws java.lang.ClassNotFoundException

Generate documentation for all fields that are derived from a specific base class. The class inheritance tree is traversed up to and including NamedObj and then the traversal stops.

Parameters:

classDoc - The ClassDoc for the class we are documenting.

fieldBaseClass - The base class for the field we are documenting.

element - The XML element that is generated.

Returns:

The documentation for all fields that are derived from the fieldBaseClass parameter.

Throws:

java.lang.ClassNotFoundException - If the class of a field cannot be found.

_getOutputDirectory

private static java.lang.String _getOutputDirectory(java.lang.String[][] options)

Process the doclet command line arguments and return the value of the -d parameter, if any.

Parameters:

options - The command line options.

Returns:

the value of the -d parameter, if any, otherwise return null.

_relativizePath

private static java.lang.String _relativizePath(java.lang.String baseDirectory,
                                                java.lang.String destinationClassName,
                                                com.sun.javadoc.ProgramElementDoc programElementDoc,
                                                boolean isIncluded)

Given two dot separated classpath names, return a relative path to the corresponding doc file. This method is used to create relative paths

Parameters:

baseDirectory - The top level directory where the classes are written.

destinationClassName - The dot separated fully qualified class name.

programElementDoc - The documentation for the base class.

isIncluded - True if the destination class is included in the set of classes we are documenting. If isIncluded is true, we create a link to the .xml file. If isIncluded is false, we create a linke to the javadoc .html file.

Returns:

a relative path from the base class to the destination class.

_writeDoc

private static void _writeDoc(java.lang.String className,
                              java.lang.String documentation)
                       throws java.io.IOException

Write the output to a file.

Parameters:

className - The dot separated fully qualified classname, which is used to specify the directory and filename to which the documentation is written.

documentation - The documentation that is written.

Throws:

java.io.IOException - If there is a problem writing the documentation.