de.kruis.padoclet
Class RefCheckDoclet

java.lang.Object
  extended by de.kruis.padoclet.RefCheckDoclet

public class RefCheckDoclet
extends java.lang.Object

This doclet creates warnings for references to undocumented items.

Sometimes your javadoc documentation of a public method contains a reference (i.e. "see" or "link"-tags) to an undocumented private method. Usually you do not want such a reference, because the reader of the of your documentation can't make any use of it. This doclet helps you to avoid such dangling references. It emits a warning, if a reference points to an undocumented item, for witch the source is available. (You don't want a warning for a reference to an undocumented item without source-code, like java.lang.Object.)

In contrast to PublishedApiDoclet this class is a conventional doclet without any magic. The only connection to PublishedApiDoclet is the PublishedApiDoclet option -padWarnOn, that makes PublishedApiDoclet to call this doclet.


Nested Class Summary
protected static class RefCheckDoclet.Option
          Option handling for doclets.
 
Field Summary
private  com.sun.javadoc.DocErrorReporter errorReporter
           
static java.lang.String OPTION_WARN_ON
           
static java.lang.String WARNING_ALL
           
static java.lang.String WARNING_ANNOTATION
           
static java.lang.String WARNING_ANNOTATION_DEFAULT_VALUE
           
static java.lang.String WARNING_ANNOTATION_ELEMENT
           
static java.lang.String WARNING_CONTAINING_CLASS
           
static java.lang.String WARNING_CONTAINING_PACKAGE
           
static java.lang.String WARNING_FIELD_TYPE
           
static java.lang.String WARNING_IMPLEMENTED_INTERFACE
           
static java.lang.String WARNING_NESTED_CLASS
           
static java.lang.String WARNING_OVERRIDDEN_METHOD
           
static java.lang.String WARNING_PARAMETER_TYPE
           
static java.lang.String WARNING_PRIVATE_ANNOTATION
           
static java.lang.String WARNING_RETURN_TYPE
           
static java.lang.String WARNING_SEE_OR_LINK_REFERENCE
           
static java.lang.String WARNING_SUPER_CLASS
           
static java.lang.String WARNING_THROWN_CLASS
           
private  java.util.Set<java.lang.String> warnOn
           
 
Constructor Summary
RefCheckDoclet()
          Create a new RefCheckDoclet instance.
 
Method Summary
private  void check(com.sun.javadoc.AnnotationTypeElementDoc elementDoc)
          Check an annotation type element doc.
private  void check(com.sun.javadoc.ClassDoc doc)
          Check a class doc.
private  void check(com.sun.javadoc.ExecutableMemberDoc emember)
          Check an executable member doc.
private  void check(com.sun.javadoc.FieldDoc field)
          Check a field doc.
private  void check(com.sun.javadoc.MethodDoc method)
          Check a method doc.
(package private)  boolean check(com.sun.javadoc.RootDoc root)
          Check for references to undocumented items.
private  void checkAnnotations(com.sun.javadoc.Doc doc, com.sun.javadoc.AnnotationDesc[] annotations)
          Check an array of annotations
private  void checkDoc(com.sun.javadoc.Doc doc)
          Check the tags of a Doc-Interface.
private  void checkReference(com.sun.javadoc.Doc doc, com.sun.javadoc.AnnotationDesc annotationDesc, java.lang.String warning)
          Check an AnnotationDesc-Interface.
private  void checkReference(com.sun.javadoc.Doc doc, com.sun.javadoc.AnnotationValue annotationValue, java.lang.String warning)
          Check an AnnotationValue-Interface.
private  void checkReference(com.sun.javadoc.Doc doc, com.sun.javadoc.ClassDoc classDoc, java.lang.String warning)
          Check a ClassDoc-Interface.
private  void checkReference(com.sun.javadoc.Doc doc, com.sun.javadoc.Doc referenced, java.lang.String warning)
          Check a Doc-Interface.
private  void checkReference(com.sun.javadoc.Doc doc, com.sun.javadoc.Type type, java.lang.String warning)
          Check a type-Interface.
private  void checkTags(com.sun.javadoc.Doc doc, com.sun.javadoc.Tag[] tags)
          Check an array of tags.
 com.sun.javadoc.DocErrorReporter getErrorReporter()
          Get the error reporter for this doclet.
 boolean isWarnOn(java.lang.String condition)
          Warn on a certain condition?
static com.sun.javadoc.LanguageVersion languageVersion()
          Implements the doclet languageVersion method.
static void main(java.lang.String[] args)
          A main method.
static int optionLength(java.lang.String option)
          The doclet optionLength method.
 void setErrorReporter(com.sun.javadoc.DocErrorReporter errorReporter)
          Set the error reporter for this doclet.
 void setWarnOn(java.lang.String warnOn)
          Set the warnOn propertiy.
static boolean start(com.sun.javadoc.RootDoc root)
          The doclet start method.
static boolean validOptions(java.lang.String[][] options, com.sun.javadoc.DocErrorReporter reporter)
          Implements the doclet validOptions method
 

Field Detail

OPTION_WARN_ON

public static final java.lang.String OPTION_WARN_ON
See Also:
Constant Field Values

WARNING_FIELD_TYPE

public static final java.lang.String WARNING_FIELD_TYPE
See Also:
Constant Field Values

WARNING_THROWN_CLASS

public static final java.lang.String WARNING_THROWN_CLASS
See Also:
Constant Field Values

WARNING_PARAMETER_TYPE

public static final java.lang.String WARNING_PARAMETER_TYPE
See Also:
Constant Field Values

WARNING_OVERRIDDEN_METHOD

public static final java.lang.String WARNING_OVERRIDDEN_METHOD
See Also:
Constant Field Values

WARNING_RETURN_TYPE

public static final java.lang.String WARNING_RETURN_TYPE
See Also:
Constant Field Values

WARNING_NESTED_CLASS

public static final java.lang.String WARNING_NESTED_CLASS
See Also:
Constant Field Values

WARNING_IMPLEMENTED_INTERFACE

public static final java.lang.String WARNING_IMPLEMENTED_INTERFACE
See Also:
Constant Field Values

WARNING_CONTAINING_PACKAGE

public static final java.lang.String WARNING_CONTAINING_PACKAGE
See Also:
Constant Field Values

WARNING_CONTAINING_CLASS

public static final java.lang.String WARNING_CONTAINING_CLASS
See Also:
Constant Field Values

WARNING_SEE_OR_LINK_REFERENCE

public static final java.lang.String WARNING_SEE_OR_LINK_REFERENCE
See Also:
Constant Field Values

WARNING_SUPER_CLASS

public static final java.lang.String WARNING_SUPER_CLASS
See Also:
Constant Field Values

WARNING_ANNOTATION_ELEMENT

public static final java.lang.String WARNING_ANNOTATION_ELEMENT
See Also:
Constant Field Values

WARNING_ANNOTATION_DEFAULT_VALUE

public static final java.lang.String WARNING_ANNOTATION_DEFAULT_VALUE
See Also:
Constant Field Values

WARNING_ANNOTATION

public static final java.lang.String WARNING_ANNOTATION
See Also:
Constant Field Values

WARNING_PRIVATE_ANNOTATION

public static final java.lang.String WARNING_PRIVATE_ANNOTATION
See Also:
Constant Field Values

WARNING_ALL

public static final java.lang.String WARNING_ALL
See Also:
Constant Field Values

errorReporter

private com.sun.javadoc.DocErrorReporter errorReporter

warnOn

private java.util.Set<java.lang.String> warnOn
Constructor Detail

RefCheckDoclet

RefCheckDoclet()
Create a new RefCheckDoclet instance.

Method Detail

checkReference

private void checkReference(com.sun.javadoc.Doc doc,
                            com.sun.javadoc.Type type,
                            java.lang.String warning)
Check a type-Interface.

Parameters:
doc - the containing Doc-Interface
type - the Type to be checked
warning - the warning constant

checkReference

private void checkReference(com.sun.javadoc.Doc doc,
                            com.sun.javadoc.ClassDoc classDoc,
                            java.lang.String warning)
Check a ClassDoc-Interface.

Parameters:
doc - the containing Doc-Interface
classDoc - the ClassDoc to be checked
warning - the warning constant

checkReference

private void checkReference(com.sun.javadoc.Doc doc,
                            com.sun.javadoc.AnnotationDesc annotationDesc,
                            java.lang.String warning)
Check an AnnotationDesc-Interface.

Parameters:
doc - the containing Doc-Interface
annotationDesc - the AnnotationDesc to be checked
warning - the warning constant

checkReference

private void checkReference(com.sun.javadoc.Doc doc,
                            com.sun.javadoc.AnnotationValue annotationValue,
                            java.lang.String warning)
Check an AnnotationValue-Interface.

Parameters:
doc - the containing Doc-Interface
annotationValue - the value.
warning - the warning constant

checkReference

private void checkReference(com.sun.javadoc.Doc doc,
                            com.sun.javadoc.Doc referenced,
                            java.lang.String warning)
Check a Doc-Interface.

Parameters:
doc - the containing Doc-Interface
referenced - the referenced Doc to be checked
warning - the warning constant

check

boolean check(com.sun.javadoc.RootDoc root)
Check for references to undocumented items. This method starts a tree-walk of the javadoc tree and looks for references to undocumented items (classes, packages, methods, ...), where source code of the referenced item is available.

Parameters:
root - the root of the javadoc tree
Returns:
always true

checkDoc

private void checkDoc(com.sun.javadoc.Doc doc)
Check the tags of a Doc-Interface.

Parameters:
doc -

checkAnnotations

private void checkAnnotations(com.sun.javadoc.Doc doc,
                              com.sun.javadoc.AnnotationDesc[] annotations)
Check an array of annotations


checkTags

private void checkTags(com.sun.javadoc.Doc doc,
                       com.sun.javadoc.Tag[] tags)
Check an array of tags. Look for \@see or \@link tags and check the reference contained within the tag.

Parameters:
doc - the containing doc-Interface.
tags - an array of tags

check

private void check(com.sun.javadoc.ClassDoc doc)
Check a class doc.

Parameters:
doc - the class documentation

check

private void check(com.sun.javadoc.AnnotationTypeElementDoc elementDoc)
Check an annotation type element doc.

Parameters:
elementDoc - the type element doc.

check

private void check(com.sun.javadoc.MethodDoc method)
Check a method doc.

Parameters:
method - the method documentation

check

private void check(com.sun.javadoc.ExecutableMemberDoc emember)
Check an executable member doc.

Parameters:
emember - the executable member documentation

check

private void check(com.sun.javadoc.FieldDoc field)
Check a field doc.

Parameters:
field - the field documentation.

setWarnOn

public final void setWarnOn(java.lang.String warnOn)
Set the warnOn propertiy. Enables or disables warning conditions. The parameter is a comman separated list of warning names. If a name is prefixed by "-", the corresponding warning is disabled.

Parameters:
warnOn - The list of warning conditions to set.

isWarnOn

public final boolean isWarnOn(java.lang.String condition)
Warn on a certain condition?

Parameters:
condition - the condition to test
Returns:
true, if the warnig is active

getErrorReporter

public final com.sun.javadoc.DocErrorReporter getErrorReporter()
Get the error reporter for this doclet.

Returns:
Returns the errorReporter provided by the doclet core.

setErrorReporter

public final void setErrorReporter(com.sun.javadoc.DocErrorReporter errorReporter)
Set the error reporter for this doclet.

Parameters:
errorReporter - The errorReporter to set.

optionLength

public static int optionLength(java.lang.String option)
The doclet optionLength method.

Parameters:
option - the name of the option
Returns:
the length or 0, if the option is unknown
See Also:
Doclet.optionLength(java.lang.String)

validOptions

public static boolean validOptions(java.lang.String[][] options,
                                   com.sun.javadoc.DocErrorReporter reporter)
                            throws java.io.IOException
Implements the doclet validOptions method

Parameters:
options - the options
reporter - used to emit messages
Returns:
true, is everything is ok, false otherwise.
Throws:
java.io.IOException
See Also:
Doclet.validOptions(java.lang.String[][], com.sun.javadoc.DocErrorReporter)

start

public static boolean start(com.sun.javadoc.RootDoc root)
                     throws java.io.IOException
The doclet start method.

Parameters:
root - the RootDoc object
Returns:
true, if everything is ok, otherwise false.
Throws:
java.io.IOException
See Also:
Doclet.start(com.sun.javadoc.RootDoc)

languageVersion

public static com.sun.javadoc.LanguageVersion languageVersion()
Implements the doclet languageVersion method. This version of RefCheckDoclet only supports LanguageVersion.JAVA_1_5.

Returns:
the supported language version

main

public static void main(java.lang.String[] args)
A main method. This method simply calls the doclet main method.

Parameters:
args - the command line arguments
See Also:
Main.execute(java.lang.String, java.lang.String, java.lang.String[])