@ Документальная аннотация в Java

Question

Какова цель @Documented аннотации в Java?

Я видел документацию, но не мог получить от нее много. Может ли кто-нибудь указать с помощью наглядного примера

Answer 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 {

Answer 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.

Answer 3

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