Spec-Zone .ru
спецификации, руководства, описания, API
Содержание документации

Переход к 1.5 API Doclet

Вводные Примечания

Предполагается, что doclet разработчик считал документацию относительно новых 1.5 функций языка и знает об изменениях doclet, требуемых поддерживать новые функции. Этот документ только помогает разработчику в произведении тех изменений. Это не определяет все новые функции языка в 1.5.

Укажите, Что Ваш Doclet Поддерживает 1.5 Источника

Класс com.sun.javadoc. У Doclet есть новый метод, который позволяет doclets указывать, какая версия Языка программирования Java поддерживается:

Doclet.languageVersion ()

По умолчанию этот метод возвращает LanguageVersion. JAVA_1_1. Следует переопределить этот метод и возвратить LanguageVersion. JAVA_1_5.

Гарантируйте, Что Ваш Doclet Обрабатывает Примитивы Должным образом

Учитывая Тип, большинство doclets различает классы и примитивы при использовании следующей проверки:
   // If true, Type must be a primitive
   Type.asClassDoc() == null
В 1.5, это больше не работает, потому что есть другие типы non-classdoc помимо примитивов. Например, asClassDoc метод возвратил бы нуль для типов аннотации также. Следует найти весь occurances? Type.asClassDoc () == нуль? и замените это Type.isPrimitive ().

Используйте ClassDoc.superclassType () Вместо ClassDoc.superclass ()

ClassDoc.superclass () не может разместить определенные универсальные конструкции типа. Супертип класса () метод должен использоваться вместо этого.

Используйте ClassDoc.interfaceTypes () Вместо ClassDoc.interfaces ()

ClassDoc.interfaces () не может разместить определенные универсальные конструкции типа. interfaceTypes () метод должен использоваться вместо этого.

Введите Параметры

Обрабатывая ClassDocs и ExecutableMemberDocs, вызовите метод typeParameters (), чтобы получить формальные параметры типа. Каждый параметр может быть обработан похожим способом, которым регулярные типы являются процессами. Единственная разница - то, что у параметров типа есть границы, которые должны быть задокументированы. Границы получаются, вызывая TypeVariable.bounds ().

Вот интерфейс, который представляет переменную типа:

com.sun.javadoc. TypeVariable

Вот алгоритм что стандарт doclet использование, чтобы обработать параметры типа:

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 Для Параметров Типа

doclet получает теги @param от конструкторов и методов, вызывая ExecutableMemberDoc.paramTags (). Начиная с классов у конструкторов и методов могут быть параметры типа, тег @param может использоваться, чтобы задокументировать эти параметры типа. Их отличают при наличии угловых скобок вокруг имен. Например:
/**
 * @param <E> the type parameter for this class.
 */
public class Foo<E>
Чтобы получить они вводят параметр @param теги, вызывают ClassDoc typeParamTags () или ExecutableMemberDoc.typeParamTags ().

Теги параметра типа можно отличить от регулярных тегов параметра, вызывая ParamTag.isTypeParameter ().

Типы аннотации

Тип аннотации отличают от классов и интерфейсов, вызывая isAnnotationType () метод. Вот интерфейс, который представляет тип аннотации:

com.sun.javadoc. AnnotationTypeDoc

Получите элементы типа аннотации, вызывая элементы метода (). Есть два типа элементов:

Нет никакого способа получить точно список дополнительных и необходимых элементов от doclet API. doclet должен вручную interate через массив элементов и проверять, что значение по умолчанию является нулем. Если это - нуль, элемент требуется.

Использование Типа аннотации

Обрабатывая ProgramElementDoc, аннотация () метод нужно вызвать, чтобы получить используемые аннотации. Вот интерфейс, который инкапсулирует annoation информацию об использовании:

com.sun.javadoc. AnnotationDesc

Выполните итерации через список объектов AnnotationDesc и обработайте каждого. Вот алгоритм что стандарт doclet использование, чтобы обработать объекты 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 is more to append
           }
           // Append '}' if this is an array of values
       }
       // Append ')' if this is an array of values
    }
}
Вот выборка этого вывода:

java.lang.annotation. Цель

Значение аннотации может быть любым следующим:

Вот алгоритм что стандарт doclet использование, чтобы преобразовать аннотацию в строку:
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();
}   

Перечисления

Перечисление отличают от классов и интерфейсов, вызывая isEnum () метод. Чтобы получить список перечислимых констант, которые будут задокументированы, вызовите enumConstants () метод. Перечислимые константы возвращаются как массив объектов FieldDoc. Перечислимую константу можно отличить от регулярного поля, вызывая isEnumConstant ().

Вот выборка Перечислимой документации:

java.lang.management.MemoryType.html

Параметры Varable

Обрабатывая ExecutableMemberDoc, вызовите isVarArg (), чтобы определить, является ли последний параметр конструктора/метода аргументом var. Если это, последний параметр требует специальной обработки. Вот дополнительный код, который стандарт doclet выполняет для var args:
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()
}
Этот код должен быть вставлен в место где Вы обычно размерности массива документа. Пожалуйста, отметьте комментарий, что var args возвращается как массивы doclet API. Мы разделяем первое? []? потому что это - только часть внутреннего представления аргумента var и не должно появиться в documetation.

Подстановочные знаки

Вот интерфейс, который представляет подстановочный тип:

com.sun.javadoc. WildcardType

То, когда с подстановочным знаком встречаются, выполните итерации через списки, расширяется и границы высшего качества. Обработайте каждый связывал тот же самый способ, которым Вы обработаете регулярный тип. Вот является алгоритм стандартом doclet использование, чтобы обработать подстановочные знаки:

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])
    } 
}

Oracle и/или его филиалы Авторское право © 1993, 2012, Oracle и/или его филиалы. Все права защищены.
Свяжитесь с Нами