com.sun.tools.doclets.doccheck
Class DocCheck

java.lang.Object
  |
  +--com.sun.javadoc.Doclet
        |
        +--com.sun.tools.doclets.doccheck.DocCheck

All Implemented Interfaces:

DocCheckConstants

public class DocCheck

extends com.sun.javadoc.Doclet

implements DocCheckConstants

Checks API specifications contained in Java source files.
Generates templates for missing comments.

Multiple severity levels:

sev 1

Package, interface, or class missing comments.

sev 2

Field, constructor, or method missing comments.

sev 3

Missing, incomplete, or extraneous tags.

sev 4

Unterminated HTML in first sentence.

FUTURE: invalid @see links

Possibilities for improvement include:

• Invalid links (sev 4): See if an option can be added to JavaDoc so the doclet can process @see and @link errors, instead of having JavaDoc automatically generate the errors.
• Null comments (sev 4): After eliminating punctuation, words that are part of the method name, grammatical words (a, of, ...) and common technincal terms (object, value, ...), see if there is anything left in the comment. If not, generate a "null comment" warning, to identify "getFoo(): Returns foo." as basically uninformative.
• Drive the program from a .ini file, so special tags are identified in the file, along with the text to generate for them. Boolean and int tags then become a special case of a generalized customization facility.
  The best way to do that is to use the XML SAX parser to read a .ini file. Items to include in DEFAULTS section:
  • lineend (\n, \r, or \r\n) (newline/linefeed, carriage return) (\n, /r => "/" directory separator. \r\n => "\")
  • author tag
  • version tag

Version History:

   1.2.2 - Modified to work with 1.4 of the java platform.  Because it 
           still works with JDK 1.2, the main version number stays 1.2.   
           Corresponds to public release 1.2 Beta 2, so named 1.2b2 below. 
   1.2.1 - Options -author and -version changed to -authorID, -versionID,
           to avoid conflict with Javadoc options with same name.
   1.2  -- Param tags now recognize comma-separated lists.
           (param x,y ... | param x, y... | param x,  y...)
   1.1  -- Added singleton tags <hr> and <img>, along with
           potential singletons <tr>, <th>, <td>.
        -- Fixed reporting of unterminated Html tags to properly
           display the text that includes the tag.
        -- Fixed a bug that cause unclosed HTML tag errors to
           go unreported when extra html tags were reported.
        -- Fixed Html tag error reporting so that the errors
           are reported in the same order they occur.
        -- Fixed multiple prints of "Package" header in PackageErrors
           file when package has more than one class of error.
   1.0  -- Created from it's predecessor, DocCheck.
 

Version:

1.2

Author:

Eric Armstrong

Nested Class Summary

class	DocCheck.HtmlTag An inner class used to keep track of a tag and up to 60 characters that follow it.
class	DocCheck.ICheck Inner class that checks to see if a method is implemented by an interface the class declares or inherits.
class	DocCheck.ParamTagData An inner class that does the work of obtaining the information we need about a ParamTags.

Field Summary

protected static java.lang.String	author Name for @author tags.
protected static java.lang.String	bSet_clause The clause used to start generated comments for boolean setFoo() methods
protected static java.lang.String	bVal_clause The clause used in generated comments for boolean values
protected static boolean	classlist If true, tells the doclet to generate a file containing a list of classes that contain errors.
protected static java.lang.String	classListFile The name of the file to create when listing classes that have errors
protected static java.util.List	classSkipList Classes to skip.
protected static java.lang.String	cnr_clause The clause used to start generated comments for constructors
protected static java.lang.String	configFilename Configuration file.
protected static boolean	docletID If true, tells the doclet to add a "Generated by" line to the summary page.
protected static java.lang.String	docletVersion
protected static java.lang.String	eol Default line-terminator.
protected static java.lang.String	errorFile
protected static int	execDepth The package depth for the executive summary page.
protected static java.lang.String	execSummary
protected static java.lang.String	get_clause The clause used to start generated comments for getFoo() methods
protected java.util.List	groupList
protected static java.lang.String	ifc_clause The clause used for generated interface comments.
protected static java.lang.String	is_clause The clause used to start generated comments for isFoo() methods
protected static java.io.PrintWriter	listFile The file that gets the list of error-containing files.
protected static java.lang.String	mainFile
protected java.util.List	majorErrs
protected java.util.List	minorErrs
protected java.util.List	noErrs
protected static java.lang.String	obj_clause The clause used for object-values in constructors
protected static java.lang.String	outputDir The place where the list of error-containing classes (class.lst) will be created if the -classlist option is specified.
protected static java.lang.String	pathPrefix Used to point to the output directory.
protected static java.util.List	pkgSkipList Packages to skip.
protected static java.lang.String	pkgSummary
protected static int	selfEvidentCommentLevel The error level at which "self-evident comments are reported.
protected static char	separator The directory-name seprator string.
protected static java.lang.String	set_clause The clause used to start generated comments for setFoo() methods
protected static java.lang.String[]	singleTag HTML tags that can be safely ignored, because they need no termination
protected static java.lang.String	statsFile
protected com.sun.tools.doclets.doccheck.ErrorTracker	totalErrors The sum of all errors.
protected static java.lang.String	val_clause The clause used to end generated comments for non-boolean values
protected static java.lang.String	version String for @version tags.
protected static java.lang.String	versionTitle Title line for report.
protected java.lang.String	windowTitle

Fields inherited from interface com.sun.tools.doclets.doccheck.DocCheckConstants

badTextColor, CLASS_ERR, CLASS_TAG, CONSTR_ERR, DEFAULT_CONSTR, ERR_CATEGORY_COUNT, ERR_TYPE_COUNT, EXC_EXTRA, EXC_INVALID, EXC_MISSING, EXC_TEXT, EXECUTABLE_ERR, FIELD_ERR, HTML_BODY, HTML_ERROR, HTML_EXTRA, HTML_FIRST, HTML_LIST, HTML_NO_PERIOD, HTML_UNCLOSED, IFC_ERR, IMPLEMENTS, INNER_ERR, INVALID_TAG, MAJOR_ERR, MEMBER_ERR, METHOD_ERR, METHOD_TAG, NO_COMMENT, NO_EVIDENT, NO_SINCE, NO_TEXT, NONE, OVERRIDES, PKG_ERR, RET_EXTRA, RET_INVALID, RET_MISSING, RET_TEXT, SEE_INVALID, SEE_MISSING, SEE_TAG, SEE_TEXT, SELF_EVIDENT, TAG_ERR, TAG_EXTRA, TAG_INVALID, TAG_MISSING, TAG_MULTVER, TAG_SPACER, TAG_TEXT, TEXT_ERR, TYPE_ERR, WARNING

Constructor Summary

DocCheck()

Method Summary

java.lang.String	article(java.lang.String s) Returns the proper article (a or an) to go along with a word, depending on its first letter, plus a space.
void	byline(HtmlTagWriter h)
java.lang.String	categoryAnchor(int level, HtmlTagWriter h)
java.lang.String	categoryHeader(int level, java.lang.String type, HtmlTagWriter h)
boolean	checkFirstSentence(java.lang.String text, com.sun.tools.doclets.doccheck.ErrorTracker et) Check the first sentence for correctness.
boolean	checkHTML(java.lang.String text, com.sun.tools.doclets.doccheck.ErrorTracker et) Check text for incomplete html tags.
boolean	checkTags(int level, com.sun.javadoc.ClassDoc cd, com.sun.tools.doclets.doccheck.ErrorTracker et) Check the tags for a class.
boolean	checkTags(int level, com.sun.javadoc.ExecutableMemberDoc emd, com.sun.tools.doclets.doccheck.ErrorTracker et) Check parameter tags for methods and constructors, plus then return tag for methods.
void	endDoc(HtmlTagWriter h) Finish the Html file.
int	endOfFirstSentence(java.lang.String text) Return the index that identifies the end of the first sentence.
void	explainClassPage(HtmlTagWriter h)
void	explainExecPage(HtmlTagWriter h)
void	explainPkgPage(HtmlTagWriter h)
void	explainPkgSummary(HtmlTagWriter h)
void	explainStatsPage(HtmlTagWriter h)
void	firstLine(int level, com.sun.javadoc.ClassDoc d, com.sun.tools.doclets.doccheck.ErrorTracker et) Adds the first line for a class comment.
void	firstLine(int level, com.sun.javadoc.ConstructorDoc d, com.sun.tools.doclets.doccheck.ErrorTracker et) Adds the first line for a constructor.
boolean	firstLine(int level, com.sun.javadoc.MethodDoc d, com.sun.tools.doclets.doccheck.ErrorTracker et) Adds the first line for the method comment.
static java.lang.String	getAuthor() Returns the name used for @author tags.
static java.lang.String	getEOL() Returns the EOL value.
static java.lang.String	getVersion() Returns the version value.
java.lang.String	groupName(java.lang.String packageName) Return the name of the group that a package belongs to, as governed by the -execDepth setting.
java.lang.String	initialText(java.lang.String s) Returns first 20 characters of a string.
boolean	initUpper(java.lang.String s) Returns true if the string starts with an uppercase letter.
HtmlTagWriter	makeWriter(java.lang.String filename) Create an HtmlTagWriter using the encoding-specification that JavaDoc so kindly left for us in the static Configuration class.
boolean	methodExists(java.lang.String name, com.sun.javadoc.ExecutableMemberDoc emd) Returns true if the containing object has a method with the given name.
int	minIndex(int i, int j) Return the minimum of two indexes if > -1, and return -1 only if both indexes = -1.
void	mkdir(java.lang.String path)
java.lang.String	name(com.sun.javadoc.ClassDoc cd) Return a string containing the non-qualified class name that uses "$" to separate inner classes from outer classes instead of ".".
static int	optionLength(java.lang.String option) Returns the "length" of a given option.
void	overrideMessage(int level, com.sun.javadoc.MethodDoc md, com.sun.tools.doclets.doccheck.ErrorTracker et) Adds a line identifying the overridden method
java.lang.String	paramPhrase(com.sun.javadoc.ExecutableMemberDoc emd, java.lang.String type) Returns an article (a or an) plus the string, depending on its initial letter (in the general case) or a somewhat more specialized version for booleans, ints, and arrays.
java.lang.String	parse(java.lang.String s) Breaks a string into component names.
void	printClassErrors(com.sun.tools.doclets.doccheck.ErrorTracker et, HtmlTagWriter h) Print errors for a class.
java.lang.String	printClassPage(java.lang.String pkgName, java.lang.String relpath, com.sun.tools.doclets.doccheck.ErrorTracker et)
void	printErrorPages()
void	printExecutiveSummary()
void	printIndexPage()
void	printMemberErrors(int level, java.lang.String prefix, com.sun.tools.doclets.doccheck.ErrorTracker et, HtmlTagWriter h)
void	printMemberTable(int level, java.lang.String prefix, com.sun.tools.doclets.doccheck.ErrorTracker et, HtmlTagWriter h)
void	printPackageErrors()
void	printPackagePage(com.sun.tools.doclets.doccheck.PkgTracker pet)
void	printPackageSummary()
void	printPkgErrors(com.sun.tools.doclets.doccheck.ErrorTracker et, HtmlTagWriter h) Print errors for a package.
void	printStatisticsPage()
boolean	processClasses(com.sun.javadoc.ClassDoc[] cd, boolean inner, com.sun.tools.doclets.doccheck.ErrorTracker owner) Process classes.
boolean	processConstructors(com.sun.javadoc.ConstructorDoc[] cd, com.sun.tools.doclets.doccheck.ErrorTracker clet) Process the constructors in a class.
boolean	processFields(com.sun.javadoc.FieldDoc[] fd, com.sun.tools.doclets.doccheck.ErrorTracker clet) Process the fields in the class.
boolean	processMethods(com.sun.javadoc.ClassDoc cd, com.sun.javadoc.MethodDoc[] md, com.sun.tools.doclets.doccheck.ErrorTracker clet) Process the methods in a class.
void	processPackages(com.sun.javadoc.PackageDoc[] pd) Process each package and the classes/interfaces within it.
java.lang.String	propertyName(com.sun.javadoc.MethodDoc d) Returns the name of the property for methods with names like isFoo(), getFoo(), and setFoo().
java.lang.String	qualifiedName(com.sun.javadoc.ClassDoc cd) Return a string containing the qualified class name that uses "$" to separate inner classes from outer classes instead of ".".
boolean	reportErrors(java.util.SortedSet errorList, com.sun.tools.doclets.doccheck.ErrorTracker et)
java.lang.String	returnPhrase(com.sun.javadoc.MethodDoc d, java.lang.String type) Returns an article (a or an) plus the string, depending on its intitial letter and whether or not the type is an array.
static void	setAuthor(java.lang.String s) Sets the string used for @author tags.
static void	setClassSkipList(java.lang.String s) Initialize the list of classes to skip.
static void	setEOL(java.lang.String s) Set the EOL value.
static void	setPkgSkipList(java.lang.String s) Initialize the list of packages to skip.
static void	setTitle(java.lang.String s) Set the title string.
static void	setVersion(java.lang.String s) Set the version value.
java.lang.String	signature(com.sun.javadoc.ConstructorDoc cd) Returns the signature for a constructor.
java.lang.String	signature(com.sun.javadoc.MethodDoc md) Returns the signature for a method.
java.lang.String	simpleName(java.lang.String s) Remove the package prefix and array subscripts from a name.
java.lang.String	squashBlanks(java.lang.String s) Compress multiple spaces down to one.
static boolean	start(com.sun.javadoc.RootDoc root) DocLet-mandated start method.
void	startDoc(java.lang.String pageTitle, java.lang.String windowTitle, HtmlTagWriter h) Print the Html file header.
protected void	startGeneration(com.sun.javadoc.RootDoc root) Find errors and generate error messages for each package and class specified on the command line.
void	stats4(int n, HtmlTagWriter h)
void	stats4(int n1, int n2, int n3, int n4, HtmlTagWriter h) Print 4 numbers (ints)
void	stats4p(java.lang.String n1, java.lang.String n2, java.lang.String n3, java.lang.String n4, HtmlTagWriter h) Print 4 percentages (longs)
void	statsRow(java.lang.String s, HtmlTagWriter h) Start a statistics row
void	statsRowEnd(HtmlTagWriter h)
void	statsTableHeader(java.lang.String title, HtmlTagWriter h)
void	summaryTableHeader(java.lang.String title, HtmlTagWriter h)
java.lang.String	today() Get the day and date information for today.
java.lang.String	typePhrase(java.lang.String type) Returns a plural phrase if the argument is an array, else returns a singular phrase.
void	typeTableHeader(java.lang.String title, HtmlTagWriter h)
java.lang.String	uncap(java.lang.String name) Returns a properly capitalized name.
static boolean	validOptions(java.lang.String[][] options, com.sun.javadoc.DocErrorReporter reporter) After parsing the available options using optionLength(java.lang.String), JavaDoc invokes this method with an array of options-arrays, where the first item in any array is the option, and subsequent items in that array are its arguments.

Methods inherited from class java.lang.Object

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

Field Detail

docletID

protected static boolean docletID

If true, tells the doclet to add a "Generated by" line to the summary page.

docletVersion

protected static java.lang.String docletVersion

configFilename

protected static java.lang.String configFilename

Configuration file. (A properties file)

cnr_clause

protected static java.lang.String cnr_clause

The clause used to start generated comments for constructors

obj_clause

protected static java.lang.String obj_clause

The clause used for object-values in constructors

get_clause

protected static java.lang.String get_clause

The clause used to start generated comments for getFoo() methods

set_clause

protected static java.lang.String set_clause

The clause used to start generated comments for setFoo() methods

is_clause

protected static java.lang.String is_clause

The clause used to start generated comments for isFoo() methods

val_clause

protected static java.lang.String val_clause

The clause used to end generated comments for non-boolean values

bSet_clause

protected static java.lang.String bSet_clause

The clause used to start generated comments for boolean setFoo() methods

bVal_clause

protected static java.lang.String bVal_clause

The clause used in generated comments for boolean values

ifc_clause

protected static java.lang.String ifc_clause

The clause used for generated interface comments.

classListFile

protected static java.lang.String classListFile

The name of the file to create when listing classes that have errors

singleTag

protected static java.lang.String[] singleTag

HTML tags that can be safely ignored, because they need no termination

author

protected static java.lang.String author

Name for @author tags.

versionTitle

protected static java.lang.String versionTitle

Title line for report.

pathPrefix

protected static java.lang.String pathPrefix

Used to point to the output directory.

version

protected static java.lang.String version

String for @version tags. Default version string = Sun standard version-markers

eol

protected static java.lang.String eol

Default line-terminator. Defaults to NL (=LF) rather than system-specific terminator, in case it is being used over a network.

classlist

protected static boolean classlist

If true, tells the doclet to generate a file containing a list of classes that contain errors. (Useful for checking out files from a source control system, for counting errors, or for a cursory review of where the errors are found.)

separator

protected static char separator

The directory-name seprator string.

outputDir

protected static java.lang.String outputDir

The place where the list of error-containing classes (class.lst) will be created if the -classlist option is specified.

listFile

protected static java.io.PrintWriter listFile

The file that gets the list of error-containing files.

totalErrors

protected com.sun.tools.doclets.doccheck.ErrorTracker totalErrors

The sum of all errors.

selfEvidentCommentLevel

protected static int selfEvidentCommentLevel

The error level at which "self-evident comments are reported. Self-evident comments are those that can be automatically generated from the text of the method name. The default is to treat them the same as other comments. That can be changed with the -evident command line switch. For example, "-evident 2" downgrades them to the level of a tag error, while "-evident 3" downgrades them to a text error. To downgrade them to a warning, use "-evident 4".

See Also:

firstLine(int, com.sun.javadoc.ClassDoc, com.sun.tools.doclets.doccheck.ErrorTracker)

pkgSkipList

protected static java.util.List pkgSkipList

Packages to skip.

classSkipList

protected static java.util.List classSkipList

Classes to skip.

execDepth

protected static int execDepth

The package depth for the executive summary page. Default is one (java.*, javax.*). Change with the -execDepth option. Set to 2 for use on the Java platform, to give summaries for java.applet.*, java.awt.*, etc.

mainFile

protected static java.lang.String mainFile

execSummary

protected static java.lang.String execSummary

pkgSummary

protected static java.lang.String pkgSummary

statsFile

protected static java.lang.String statsFile

errorFile

protected static java.lang.String errorFile

groupList

protected java.util.List groupList

majorErrs

protected java.util.List majorErrs

minorErrs

protected java.util.List minorErrs

noErrs

protected java.util.List noErrs

windowTitle

protected java.lang.String windowTitle

Constructor Detail

DocCheck

public DocCheck()

Method Detail

getAuthor

public static java.lang.String getAuthor()

Returns the name used for @author tags. The default author name = "unknown".

Returns:

a String containing the author name.

setAuthor

public static void setAuthor(java.lang.String s)

Sets the string used for @author tags.

Parameters:

s - a String ...

getVersion

public static java.lang.String getVersion()

Returns the version value.

Returns:

the String used for the @version tag.

setVersion

public static void setVersion(java.lang.String s)

Set the version value.

Parameters:

s - a String to use for the @version tag

setTitle

public static void setTitle(java.lang.String s)

Set the title string.

Parameters:

s - a String to use for the report

getEOL

public static java.lang.String getEOL()

Returns the EOL value.

Returns:

the String that ends lines.

setEOL

public static void setEOL(java.lang.String s)

Set the EOL value.

Parameters:

s - a String to use as the line terminator

setPkgSkipList

public static void setPkgSkipList(java.lang.String s)

Initialize the list of packages to skip.

Parameters:

s - a list of package-patterns separated by the current system's path separator (":" for Unix, ";" for DOS), where each pattern is a fully-qualified path separated by "." characters.

See Also:

PathSpecifier

setClassSkipList

public static void setClassSkipList(java.lang.String s)

Initialize the list of classes to skip.

Parameters:

s - a list of classname-patterns separated by the current system's path separator (":" for Unix, ";" for DOS), where each pattern is a fully-qualified classname, as described in FileSpecifier

start

public static boolean start(com.sun.javadoc.RootDoc root)

DocLet-mandated start method. Everything begins here.

Parameters:

root - a RootDoc object passed by JavaDoc

Returns:

true if document generation succeeds

startGeneration

protected void startGeneration(com.sun.javadoc.RootDoc root)

Find errors and generate error messages for each package and class specified on the command line.

Parameters:

root - the RootDoc object passed by JavaDoc

printErrorPages

public void printErrorPages()

printPackageErrors

public void printPackageErrors()

printStatisticsPage

public void printStatisticsPage()

printPackageSummary

public void printPackageSummary()

printExecutiveSummary

public void printExecutiveSummary()

printIndexPage

public void printIndexPage()

byline

public void byline(HtmlTagWriter h)

groupName

public java.lang.String groupName(java.lang.String packageName)

Return the name of the group that a package belongs to, as governed by the -execDepth setting.

Parameters:

packageName - the full package name

Returns:

String the package group (with no ".*")

printPackagePage

public void printPackagePage(com.sun.tools.doclets.doccheck.PkgTracker pet)

printClassPage

public java.lang.String printClassPage(java.lang.String pkgName,
                                       java.lang.String relpath,
                                       com.sun.tools.doclets.doccheck.ErrorTracker et)

mkdir

public void mkdir(java.lang.String path)

categoryAnchor

public java.lang.String categoryAnchor(int level,
                                       HtmlTagWriter h)

categoryHeader

public java.lang.String categoryHeader(int level,
                                       java.lang.String type,
                                       HtmlTagWriter h)

printPkgErrors

public void printPkgErrors(com.sun.tools.doclets.doccheck.ErrorTracker et,
                           HtmlTagWriter h)

Print errors for a package.

printClassErrors

public void printClassErrors(com.sun.tools.doclets.doccheck.ErrorTracker et,
                             HtmlTagWriter h)

Print errors for a class. Process messages and the sub list for category 1 errors, then category 2, etc.

printMemberErrors

public void printMemberErrors(int level,
                              java.lang.String prefix,
                              com.sun.tools.doclets.doccheck.ErrorTracker et,
                              HtmlTagWriter h)

printMemberTable

public void printMemberTable(int level,
                             java.lang.String prefix,
                             com.sun.tools.doclets.doccheck.ErrorTracker et,
                             HtmlTagWriter h)

summaryTableHeader

public void summaryTableHeader(java.lang.String title,
                               HtmlTagWriter h)

typeTableHeader

public void typeTableHeader(java.lang.String title,
                            HtmlTagWriter h)

statsRow

public void statsRow(java.lang.String s,
                     HtmlTagWriter h)

Start a statistics row

stats4p

public void stats4p(java.lang.String n1,
                    java.lang.String n2,
                    java.lang.String n3,
                    java.lang.String n4,
                    HtmlTagWriter h)

Print 4 percentages (longs)

stats4

public void stats4(int n1,
                   int n2,
                   int n3,
                   int n4,
                   HtmlTagWriter h)

Print 4 numbers (ints)

stats4

public void stats4(int n,
                   HtmlTagWriter h)

statsRowEnd

public void statsRowEnd(HtmlTagWriter h)

statsTableHeader

public void statsTableHeader(java.lang.String title,
                             HtmlTagWriter h)

explainExecPage

public void explainExecPage(HtmlTagWriter h)

explainStatsPage

public void explainStatsPage(HtmlTagWriter h)

explainPkgSummary

public void explainPkgSummary(HtmlTagWriter h)

explainPkgPage

public void explainPkgPage(HtmlTagWriter h)

explainClassPage

public void explainClassPage(HtmlTagWriter h)

makeWriter

public HtmlTagWriter makeWriter(java.lang.String filename)

Create an HtmlTagWriter using the encoding-specification that JavaDoc so kindly left for us in the static Configuration class.

Parameters:

filename - a path to a file, relative to the output directory.

today

public java.lang.String today()

Get the day and date information for today. Uses:

• java.util.Calender
• java.util.GregorianCalendar
• java.util.TimeZone

Returns:

String Today.

startDoc

public void startDoc(java.lang.String pageTitle,
                     java.lang.String windowTitle,
                     HtmlTagWriter h)

Print the Html file header.

Parameters:

windowTitle - Title of this HTML document.

endDoc

public void endDoc(HtmlTagWriter h)

Finish the Html file.

processPackages

public void processPackages(com.sun.javadoc.PackageDoc[] pd)

Process each package and the classes/interfaces within it.

Parameters:

pd - an array of PackageDoc objects

processClasses

public boolean processClasses(com.sun.javadoc.ClassDoc[] cd,
                              boolean inner,
                              com.sun.tools.doclets.doccheck.ErrorTracker owner)

Process classes. Listed classes are those that were listed on the command line. Names of such classes are always output. Unlisted classes are contained in specified packages. Names of these classes are only listed if there was an error.

Ideally, we would process all members of the class in the order they are specified in the file. However, we can only approximate that order. JavaDoc gives us fields, constructors, methods, and inner classes. Each of those groupings is in file order, and the the fields/constructors/methods/innerClasses is the most frequently found ordering of the groups. [Future: provide an option to control ordering.]

Parameters:

cd - an array of ClassDoc objects

inner - a boolean -- true if ...

owner - the ErrorTracker object collecting the errors

Returns:

true if ...

checkFirstSentence

public boolean checkFirstSentence(java.lang.String text,
                                  com.sun.tools.doclets.doccheck.ErrorTracker et)

Check the first sentence for correctness.

Parameters:

text - the text containing the first sentence

et - the ErrorTracker object collecting the errors

endOfFirstSentence

public int endOfFirstSentence(java.lang.String text)

Return the index that identifies the end of the first sentence.

Parameters:

text - the text to check

Returns:

an int pointing the end of the sentence, or -1 if end of sentence is not found.

minIndex

public int minIndex(int i,
                    int j)

Return the minimum of two indexes if > -1, and return -1 only if both indexes = -1.

Parameters:

i - an int index

j - an int index

Returns:

an int equal to the minimum index > -1, or -1

checkHTML

public boolean checkHTML(java.lang.String text,
                         com.sun.tools.doclets.doccheck.ErrorTracker et)

Check text for incomplete html tags.

Parameters:

text - the text to check

et - the ErrorTracker object collecting the errors

reportErrors

public boolean reportErrors(java.util.SortedSet errorList,
                            com.sun.tools.doclets.doccheck.ErrorTracker et)

squashBlanks

public java.lang.String squashBlanks(java.lang.String s)

Compress multiple spaces down to one.

Parameters:

s - the string to squash

name

public java.lang.String name(com.sun.javadoc.ClassDoc cd)

Return a string containing the non-qualified class name that uses "$" to separate inner classes from outer classes instead of ".".

Returns:

a String containing the non-qualified name

qualifiedName

public java.lang.String qualifiedName(com.sun.javadoc.ClassDoc cd)

Return a string containing the qualified class name that uses "$" to separate inner classes from outer classes instead of ".".

Returns:

a String containing the qualified name

processFields

public boolean processFields(com.sun.javadoc.FieldDoc[] fd,
                             com.sun.tools.doclets.doccheck.ErrorTracker clet)

Process the fields in the class.

Parameters:

fd - an array of FieldDoc objects

clet - the ErrorTracker object collecting the errors

Returns:

true if the processing succeeded

processConstructors

public boolean processConstructors(com.sun.javadoc.ConstructorDoc[] cd,
                                   com.sun.tools.doclets.doccheck.ErrorTracker clet)

Process the constructors in a class.

Parameters:

cd - an array of ConstructorDoc objects

clet - the ErrorTracker object collecting the errors

Returns:

true if the processing succeeded

processMethods

public boolean processMethods(com.sun.javadoc.ClassDoc cd,
                              com.sun.javadoc.MethodDoc[] md,
                              com.sun.tools.doclets.doccheck.ErrorTracker clet)

Process the methods in a class.

Parameters:

md - an array of MethodDoc objects

clet - the ErrorTracker object collecting the errors

Returns:

true if the processing succeeded

firstLine

public void firstLine(int level,
                      com.sun.javadoc.ClassDoc d,
                      com.sun.tools.doclets.doccheck.ErrorTracker et)

Adds the first line for a class comment. For an interface, adds "Defines the requirements for an object that ..." . For a class, adds a tag spacer (" *").

Parameters:

d - a ClassDoc object

et - the ErrorTracker object collecting the errors

firstLine

public void firstLine(int level,
                      com.sun.javadoc.ConstructorDoc d,
                      com.sun.tools.doclets.doccheck.ErrorTracker et)

Adds the first line for a constructor.

Parameters:

d - a ConstructorDoc object

et - the ErrorTracker object collecting the errors

firstLine

public boolean firstLine(int level,
                         com.sun.javadoc.MethodDoc d,
                         com.sun.tools.doclets.doccheck.ErrorTracker et)

Adds the first line for the method comment. Identifies an overridden method, if there is one. For "getFoo" adds "Returns the foo value." For "setFoo", adds "Sets the foo value." For "isFoo", adds "Returns the foo value". (These are the default phrases, which can be controlled using command-line options.) See DocCheck.html for details.

Parameters:

d - a MethodDoc object

et - the ErrorTracker object collecting the errors

overrideMessage

public void overrideMessage(int level,
                            com.sun.javadoc.MethodDoc md,
                            com.sun.tools.doclets.doccheck.ErrorTracker et)

Adds a line identifying the overridden method

Parameters:

md - a MethodDoc object

et - the ErrorTracker object collecting the errors

propertyName

public java.lang.String propertyName(com.sun.javadoc.MethodDoc d)

Returns the name of the property for methods with names like isFoo(), getFoo(), and setFoo(). Returns the property name with a lowercase initial letter.

Parameters:

d - a MethodDoc object

Returns:

a String containing the property name, or null

parse

public java.lang.String parse(java.lang.String s)

Breaks a string into component names. For a string like ReallyFoo, returns "really foo". Does not attempt to break up strings of capital letters, so AnABC() returns "an ABC" and "VeryGoodABs()" returns "very good ABs". This processing will therefore break up "ALLgoodThings" as "ALLgood things". Similarly, "ALLGoodThings" is returned as "ALLGood things". Since there is no universal standard about how to capitalize the word following a string of capitals, this parsing is the best that can be achieved.

Parameters:

s - an intercap string to break up

Returns:

a String with initial lowercase names and spaces between them

uncap

public java.lang.String uncap(java.lang.String name)

Returns a properly capitalized name. Name is assumed to be at least 2 characters long. Initial letter is assumed to be upper case. It is converted to lower case if the second letter is also lower case.

Parameters:

name - a String containing a name

Returns:

the String with the first letter capitalized properly for a property name

checkTags

public boolean checkTags(int level,
                         com.sun.javadoc.ClassDoc cd,
                         com.sun.tools.doclets.doccheck.ErrorTracker et)

Check the tags for a class.

Parameters:

level - an int that selects the error-reporting object that generated-tags will be added to. (Used when generating tags for class, constructor, and method templates, and only when no tags exist.)

cd - a ClassDoc object

et - the ErrorTracker object collecting the errors

Returns:

true if no errors were found

checkTags

public boolean checkTags(int level,
                         com.sun.javadoc.ExecutableMemberDoc emd,
                         com.sun.tools.doclets.doccheck.ErrorTracker et)

Check parameter tags for methods and constructors, plus then return tag for methods.

Parameters:

level - an int that selects the error-reporting object that generated-tags will be added to. (Used when generating tags for class, constructor, and method templates when no tags exist.)

emd - a ExecutableMemberDoc object

et - the ErrorTracker object collecting the errors

Returns:

true if there were no errors

methodExists

public boolean methodExists(java.lang.String name,
                            com.sun.javadoc.ExecutableMemberDoc emd)

Returns true if the containing object has a method with the given name.

Parameters:

name - a String specifying the name of the method

emd - an ExecutableMemberDoc object

Returns:

true if the associated method exists

initialText

public java.lang.String initialText(java.lang.String s)

Returns first 20 characters of a string.

Returns:

a String containing first 20 characters of the input string.

returnPhrase

public java.lang.String returnPhrase(com.sun.javadoc.MethodDoc d,
                                     java.lang.String type)

Returns an article (a or an) plus the string, depending on its intitial letter and whether or not the type is an array.

Parameters:

type - a String identifying a type

Returns:

the String containing the phrase to use for that type

initUpper

public boolean initUpper(java.lang.String s)

Returns true if the string starts with an uppercase letter.

Parameters:

s - a String

Returns:

true if the string starts with an upper case letter

paramPhrase

public java.lang.String paramPhrase(com.sun.javadoc.ExecutableMemberDoc emd,
                                    java.lang.String type)

Returns an article (a or an) plus the string, depending on its initial letter (in the general case) or a somewhat more specialized version for booleans, ints, and arrays.

Parameters:

type - a String identifying a type

Returns:

the String containing the phrase to use for that type

typePhrase

public java.lang.String typePhrase(java.lang.String type)

Returns a plural phrase if the argument is an array, else returns a singular phrase.

Parameters:

type - a String containing a data type

Returns:

a String containing the appropriate phrase for that type

article

public java.lang.String article(java.lang.String s)

Returns the proper article (a or an) to go along with a word, depending on its first letter, plus a space.

simpleName

public java.lang.String simpleName(java.lang.String s)

Remove the package prefix and array subscripts from a name.

Parameters:

s - a String containing a fully qualified name

Returns:

the String containing the name without the package qualifier or array subscripts

signature

public java.lang.String signature(com.sun.javadoc.MethodDoc md)

Returns the signature for a method.

Parameters:

md - a MethodDoc object produced by JavaDoc

Returns:

the String containing the method signature

signature

public java.lang.String signature(com.sun.javadoc.ConstructorDoc cd)

Returns the signature for a constructor.

Parameters:

cd - a ConstructorDoc object produced by JavaDoc

Returns:

the String containing the constructor signature

optionLength

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

Returns the "length" of a given option. If an option takes no arguments, its length is one. If it takes one argument, its length is two, and so on. This method is called by JavaDoc to parse the options it does not recognize. It then calls validOptions(java.lang.String[][], com.sun.javadoc.DocErrorReporter) to validate them.

Note:
The options arrive as case-sensitive strings. For options that are not case-sensitive, use toLowerCase() on the option string before comparing it.

Parameters:

option - a String containing an option

Returns:

an int telling how many components that option has

validOptions

public static boolean validOptions(java.lang.String[][] options,
                                   com.sun.javadoc.DocErrorReporter reporter)

After parsing the available options using optionLength(java.lang.String), JavaDoc invokes this method with an array of options-arrays, where the first item in any array is the option, and subsequent items in that array are its arguments. So, if -print is an option that takes no arguments, and -copies is an option that takes 1 argument, then

     -print -copies 3
 

produces an array of arrays that looks like:

      option[0][0] = -print
      option[1][0] = -copies
      option[1][1] = 3
 

(By convention, command line switches start with a "-", but they don't have to.)

Note:
JavaDoc passes allparameters to this method, not just those that JavaDoc doesn't recognize. The only way to identify unexpected arguments is therefore to check for every JavaDoc parameter as well as doclet parameters.

Parameters:

options - an array of String arrays, one per option

reporter - a DocErrorReporter for generating error messages

Returns:

true if no errors were found, and all options are valid