Аннотация для отключения JavaDocs
Существует ли аннотация, чтобы объявить, что определенный метод не будет включен в JavaDocs даже при том, что это общедоступно?
Что-то как:
@nojavadocs
public void foo(){
//...
}
P.S. Я понимаю точку здесь о API, но методы просто "не поддерживаются". Они работают (и должно быть общедоступным для доступа от других пакетов), но мы не хотим потрудиться документировать их и отвечать на вопросы о том, как использовать их, когда их функциональность не относится к поддерживаемым сценариям использования. Хороший дизайн мог бы означать перемещать их в другой класс, но они логически обращаются к данным в классе.
4 ответа
Нет, если вы используете инструмент Sun JavaDocs.
У них есть запрос функции для него, но он имеет низкий приоритет с 1997 года.
Вы можете написать собственный документ, чтобы преодолеть это, или использовать сторонний инструмент (DocFlex или подобный).
Да ... но не в хорошем смысле (наличие общедоступных методов, которые на самом деле не являются "общедоступными", - не лучшая практика проектирования).
Вы можете следовать предложение, данное в этой ветке , и отметьте метод с помощью @deprecated , а затем, когда вы запустите javadoc, используйте параметр -nodeprecated .
Изменить: Как отмечали другие, это не желательный курс действий. Это решит вашу проблему, но вам действительно нужно переосмыслить, почему вы хотите скрыть метод - учитывая скомпилированную версию вашего кода, кто-то все равно сможет увидеть вашу функцию; скрытие его в документации на самом деле не скрывает метод. Я действительно хочу подчеркнуть, что квалификаторы private , общедоступные и защищенные имеют значение, которое вы должны учитывать и эффективно использовать. Не существует такого понятия, как «скрытый» открытый метод .
/**
* Don't use this method <br>
* <i>or all your data will be lost.</i>
*/
public void foo(){
//...
}
ну, используйте лучшее объяснение, почему пользователь не должен использовать этот метод ...
Помните, что найти какой-либо (общедоступный) метод с помощью декомпилятора или Reflection несложно.
Единственная причина, по которой я мог подумать, что вы захотите это сделать, - это в некотором смысле «спрятать» метод, хотя бы с точки зрения документации. Если бы вы сделали это, вы бы проектировали документацию так, чтобы она была «сломанной» в том смысле, что документация становится сломанной, когда она устаревает и больше не отражает точно то, что делает класс. Поскольку метод по-прежнему является частью общедоступного API, вы все равно не скрываете его.
Если вы хотите, чтобы метод не использовался вне класса или нескольких пользователей, сделайте его частным или упакуйте. Если это неудобно и должно быть общедоступным, я бы просто очень четко задокументировал ограничения на его использование, возможно, с соглашением об именах (например, python делает это, есть имена сущностей, окруженные подчеркиванием,