Как лучше всего обрабатывать / форматировать Javadoc и аннотации в коде?

Я просмотрел этот форум, погуглил и не знаю, как лучше всего обрабатывать документацию Javadoc и аннотации, которые появляются вместе в одном классе.

Из того, что я вижу из документации Sun / Oracle, они, кажется, предлагают (хотя я не могу найти явного заявления), что Javadoc должен быть указан поверх аннотаций.

См. Их пример Как и когда прекращать использование API.

Это отлично подходит для чего-то простого, например @Deprecated или @Override. Но как насчет того, чтобы использовать JPA и / или Hibernate? Ваши классы и методы должны быть немного более сильно аннотированы (иногда две или более аннотации для каждого класса или метода).

Я предполагаю, что Javadoc все еще поверх аннотаций?

Также мне интересно, как лучше всего использовать аннотации? Я видел несколько примеров, когда аннотации «складываются» поверх класса, члена, метода. И я видел других, где они перечисляли аннотации в одной строке (обычно это метод).

Что лучше? Что более читабельно?

И вы «документируете» тот факт, что вы аннотировали что-то в своем Javadoc или нет?

Я ищу либо хороший набор документации по этому поводу, либо ваш собственный опыт о том, что является наиболее читаемым / поддерживаемым.


java formatting annotations code-documentation javadoc
person Chris Aldrich    schedule 08.08.2011    source источник
comment
Вам не нужно явно указывать, что вы добавили аннотацию; аннотации с аннотацией @Documented автоматически добавляются в документацию.   -  person Chris Jester-Young    schedule 08.08.2011

Ответы (2)


arrow_upward
7
arrow_downward

Javadoc - это только место, где вы документируете класс, метод и т. Д. Аннотации могут изменять функциональность данного кода (например, аннотации из Hibernate или Spring). Итак, для меня очевидно, что аннотации должны быть ближе к коду (то есть между javadoc и методом / функцией).

Но как писать аннотации, когда их много? В зависимости от обстоятельств, я предпочитаю оставлять их в отдельных строках, за некоторыми исключениями, если они короткие и каким-то образом связаны.

Я думаю, что явное документирование в Javadoc того, что вы используете аннотации, не является хорошей идеей. Аннотации могут иметь @Documented аннотации, в которых говорится, что они должны появляться в сгенерированных документах javadoc. Кроме того, это детали реализации - javadoc должен указывать, для чего создан метод / объект, а не как вы это делаете (в основном, по крайней мере).

person Adam Jurczyk    schedule 08.08.2011

arrow_upward
0
arrow_downward

Я думаю, вы смешиваете аннотации кода и аннотации javadoc.

Комментарии javadoc - это просто комментарии. Для вашего приложения не имеет значения, что на самом деле заключено в /** */ (если, конечно, вы не создаете javadoc)

Аннотации кода фактически влияют на функциональность вашего приложения. Классы сопоставления гибернации не будут работать, если вы опустите аннотации (и не предоставите файл конфигурации гибернации). Метод, помеченный как @Deprecated только в комментарии javadoc, но не в коде, не будет распознан компилятором как устаревший. (в этом случае инструмент javadoc, возможно, предупредит вас)

Итак, да, в коде и javadoc есть аннотации с одинаковыми именами, но они совершенно разные. В случае @Deprecated вы должны использовать оба: чтобы пометить их как устаревшие в коде, и чтобы задокументировать, почему.

person pmnt    schedule 08.08.2011
comment
нет, я их не смешиваю. Я спрашиваю, как лучше всего отформатировать их в коде, чтобы сделать код читабельным. Технически вы можете сначала перечислить аннотации, затем javadoc, а затем источник ... хотя я не уверен, почему. Я спрашиваю больше с точки зрения читабельности кода. - person Chris Aldrich; 08.08.2011
comment
ок ... Лично я считаю, что аннотации относятся к коду: javadoc - annotations - source - person pmnt; 08.08.2011