@Documented аннотация в java

Ответ 1

@Documented является мета-аннотацией. Вы применяете @Documented при определении аннотации, чтобы убедиться, что классы, использующие вашу аннотацию, показывают это в их сгенерированном JavaDoc. Я не видел много пользы от этого, но есть пример здесь. Более ранний вопрос предполагает, что он не работает автоматически в Eclipse, но я тестировал его в Eclipse 3.6, и мои аннотации появляются в всплывающих окнах JavaDoc, присоединяюсь или нет аннотация @Documented для них.

Вот пример из Spring, который гарантирует, что транзакционные методы отмечены как таковые в JavaDoc:

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface Transactional {

Ответ 2

Если какая-то наша аннотация, скажем @InWork, @Documented, то для каждого класса, имеющего @InWork, текст, сгенерированный javadoc, будет содержать текст @InWork в качестве ссылки на аннотацию.

Аннотация:

@Documented
@Inherited  // for descenders of the annotation to have the @Documented feature automatically
@Retention(RetentionPolicy.RUNTIME) // must be there
public @interface InWork {
    String value();
}

Аннотированная цель:

/**
 * Annotated class.
 */
@InWork(value = "")
public class MainApp {...}

Текст javadoc:

Итак, вы должны решить, если аннотация должна быть показана в тексте javadoc, и если да, установите для нее @Documented.

Приведенная выше информация взята из документации Oracle.

Обратите внимание, что в Eclipse вы увидите в javadoc сгенерированном тексте ВСЕ аннотации, являются ли они @Documented или нет.

Это все еще верно для версии 4.3.

Ответ 3

Я нашел полезную страницу в Java Tutorials, в которой приводятся примеры и дополнительные пояснения для ряда стандартных аннотаций, включая одно использование @Documented. В частности, посмотрите на блок Примечание внизу для примера преамбулы (раздел Документация).