5.0 ドックレット API への移行

はじめに

ドックレットが 5.0 ソースをサポートしていることを示す

Doclet.languageVersion()

デフォルトでは、このメソッドは LanguageVersion.JAVA_1_1 を返します。このメソッドが LanguageVersion.JAVA_1_5 を返すようメソッドをオーバーライドしてください。

ドックレットがプリミティブ型を適切に処理するよう保証する

   // If true, Type must be a primitive
   Type.asClassDoc() == null

ClassDoc.superclass() ではなく ClassDoc.superclassType() を使用

ClassDoc.interfaces() ではなく ClassDoc.interfaceTypes() を使用

型パラメータ

次のインタフェースが、型変数を表しています。

com.sun.javadoc.TypeVariable

次に示すのは、型パラメータを処理するために標準ドックレットが使用するアルゴリズムです。

if (type.asTypeVariable()!= null) {
    Doc owner = type.asTypeVariable().owner();
    if (owner instanceof ClassDoc) {
        // Generate Link to type Parameter
    } else {
        // No need to link method type parameters.
        // Append the name of the type parameter
    }
           
    Type[] bounds = type.asTypeVariable().bounds();
    if (! linkInfo.excludeTypeBounds) {
        for (int i = 0; i < bounds.length; i++) {
            // If i greater than 0, append " & ".  Otherwise, append " extends "
            // Generate a link to the bound
        }
    }
}

型パラメータの Param タグ

/**
 * @param <E> the type parameter for this class.
 */
public class Foo<E>

型パラメータのタグを通常のパラメータのタグと区別するには、ParamTag.isTypeParameter() を呼び出します。

注釈型

com.sun.javadoc.AnnotationTypeDoc

注釈型の要素を取得するには、メソッド elements() を呼び出します。要素には次の 2 種類があります。

• 省略可能な要素。ユーザがこの要素に値を指定しない場合、指定されたデフォルト値がこの要素に設定されます。
• 必須の要素。注釈を使用するとき、ユーザはこの要素に必ず値を指定しなければなりません。

注釈型の使用

com.sun.javadoc.AnnotationDesc

AnnotationDesc オブジェクトのリストを繰り返し処理して、各オブジェクトを処理します。次に示すのは、AnnotationDesc オブジェクトを処理するために標準ドックレットが使用するアルゴリズムです。

for (int i = 0; i < descList.length; i++) {
    AnnotationTypeDoc annotationDoc = descList[i].annotationType();
    if (/**annotationDoc does not have @documented annotation**/){
        // ONLY document annotations if they have @documented.
        continue;
    }
    // Generate a link to the annotation.  Start with the ?@? character>
    AnnotationDesc.ElementValuePair[] pairs =  
        descList[i].elementValues();           
    if (pairs.length > 0) {
        // Append '(' to indicate start of element list>
        for (int j = 0; j < pairs.length; j++) {
              if (j > 0) {
                // Append ',' to separate previous element from the next>
            }
            // Generate a link to the annotation element>
            // Append '=' to separate element name from value>
            AnnotationValue annotationValue = pairs[j].value();
            List annotationTypeValues = new ArrayList();
            if (annotationValue.value() instanceof 
                     AnnotationValue[]) {
                 AnnotationValue[] annotationArray =
                 (AnnotationValue[]) annotationValue.value();
                 for (int k = 0; k < annotationArray.length; k++) {                             
                    annotationTypeValues.add(annotationArray[k]);
                 }
           } else {
               annotationTypeValues.add(annotationValue);
           }
           // Append '{' if this is an array of values
           for (Iterator iter = 
               annotationTypeValues.iterator();
               iter.hasNext(); ) {
               // Append string representation of value
               // Append ?,? if there there is more to append
           }
           // Append '}' if this is an array of values
       }
       // Append ')' if this is an array of values
    }
}

java.lang.annotation.Target

注釈の値は、次のいずれかになります。

• 型
• 配列型
• Primitive
• 入れ子の注釈
• MemberDoc
• String

if (annotationValue.value() instanceof Type) {
    Type type = (Type) annotationValue.value();
    if (type.asClassDoc() != null) {
        LinkInfoImpl linkInfo = new LinkInfoImpl(
           LinkInfoImpl.CONTEXT_ANNOTATION, type);
        linkInfo.label = (type.asClassDoc().isIncluded() ?
            type.typeName() :
            type.qualifiedTypeName()) + type.dimension() + ".class ";
        return getLink(linkInfo);
    } else {
        return type.typeName() + type.dimension() + ".class";
    }
} else if (annotationValue.value() instanceof AnnotationDesc) {
    // Handle nested annotations using recursion.
    List list = getAnnotations(
        new AnnotationDesc[]{(AnnotationDesc) annotationValue.value()},
            false);
    StringBuffer buf = new StringBuffer();
    for (Iterator iter = list.iterator(); iter.hasNext(); ) {
        buf.append(iter.next());  
    }
    return buf.toString();
} else if (annotationValue.value() instanceof MemberDoc) {
    // Simply link to the member being references in the annotation.
    return getDocLink(LinkInfoImpl.CONTEXT_ANNOTATION,
        (MemberDoc) annotationValue.value(),
        ((MemberDoc) annotationValue.value()).name(), false);
} else {
    return annotationValue.toString();
}   

列挙型

次に示すのは、列挙型の文書の例です。

java.lang.management.MemoryType.html

可変数の引数

if (isVarArg) {
    if (type.dimension().length() > 2) {
        // Doclet API returns var args as array.
        // Strip out the first [] from the var arg.
        // Append type.dimension().substring(2)
    }
    // Append "..."
} else {
    // Append type.dimension()
}

ワイルドカード

com.sun.javadoc.WildcardType

ワイルドカードに遭遇したときは、拡張クラスとスーパークラスの境界のリストを繰り返し処理します。各境界は、通常の型を処理するのと同じ方法で処理します。次に示すのは、ワイルドカードを処理するために標準ドックレットが使用するアルゴリズムです。

if (type.asWildcardType() != null) {
    WildcardType wildcardType = type.asWildcardType();
    Type[] extendsBounds = wildcardType.extendsBounds();
    for (int i = 0; i < extendsBounds.length; i++) {
        // If i greater than 0, append " , ".  Otherwise, append " extends "
        // Generate link to extendsBounds[i])
    }
    Type[] superBounds = wildcardType.superBounds();
    for (int i = 0; i < superBounds.length; i++) {
        // If i greater than 0, append " , ".  Otherwise, append " super "
        // Generate link to superBounds[i])
    } 
}