Должен ли я использовать устаревание JavaDoc или аннотацию в Java?

В настоящий момент есть два способа маркировать код как депрессивный в java.

Через JavaDoc

/**
 * @deprecated
 */

Или как аннотация:

@Deprecated

Это моя проблема. Я считаю, что это слишком много, чтобы объявить обоим, отмечая метод как устаревший при использовании Eclipse. Я просто хочу использовать один из них.

Однако использование аннотации дает компилятору актуальную полезную дополнительную информацию?

Но только с помощью аннотации я не могу указать, почему метод устарел - я могу сделать это только с помощью JavaDoc и осуждать метод, не указав, почему это плохо.

Итак, могу ли я использовать только один из них? Или я должен просто научиться указывать оба?

Ответ 1

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

В соответствии с Oracle Java Annotations tutorial:

Когда элемент устарел, он также должен быть документирован с использованием тега Javadoc @deprecated...

Ответ 2

Из лошадиный рот:

ПРИМЕЧАНИЕ. Спецификация языка Java требует, чтобы компиляторы выдавали предупреждения когда классы, методы или поля отмечены аннотацией @Deprecated используются. Компиляторы не требуются по спецификации языка Java для выдавать предупреждения, когда классы, методы, или поля, отмеченные символом @deprecated Доступ к тегам Javadoc, хотя Составители Sun в настоящее время делают это.

Итак, в принципе, если вы хотите получить гарантию на наличие предупреждений компилятора, вам нужно использовать аннотацию. Из-за того, что некоторые разработчики API обладают невероятной некомпетентностью, вам нужно также указать тег javadoc, чтобы дать объяснение.

Лично я бы сказал, что аннотация бесполезна и должна быть опущена до тех пор, пока она не будет исправлена, поскольку любой хороший компилятор или среда IDE также будут отображать предупреждения с тегом javadoc.

Ответ 3

Вы должны указать оба.

Аннотации позволяют компилятору узнать об этом и вызывать предупреждения при использовании метода. Атрибут JavaDoc позволяет разработчикам знать, прежде чем они начнут его использовать.

Это две разные вещи!

Ответ 4

Вы должны написать оба. @Deprecated Anotation предназначена для компилятора, а тег JavaDoc, называемый @deprecated, предназначен для человека, который хочет теперь, почему это устарело.

Пример может выглядеть так:

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}

Ответ 5

Это легко справляется с хорошей IDE.

Eclipse Neon, например. автоматически добавляет @Deprecated аннотацию, когда я создаю javadoc @deprecated по методу или полю.

Итак, я просто напишу javadoc с соответствующим объяснением и дайте IDE позаботиться о добавлении аннотации @Deprecated, как только я сохраню файл.