Как исключить конкретный метод/конструктор из результатов задачи javadoc Ant?

Я использую javadocs, сгенерированные с помощью задачи javadoc Ant для документирования веб-службы, и я хочу исключить некоторые конструкторы из вывода. Как это сделать?

Ответы

Ответ 1

Нет способа сделать это для общедоступных методов. Стандартная практика (даже в довольно многих классах JDK) заключается в том, чтобы указать, что метод или конструктор не предназначены для общественного использования.

Существует планировать добавление тега @exclude в будущем:

@exclude - для API, который должен быть исключен из поколение Javadoc. Программист будет отмечать класс, интерфейс, конструктор, метод или поле с @exclude. Наличие тега вызовет API, который должен быть исключен из сгенерированного документация. Текст, следующий за тегом может объяснить причину исключения, но Джавадок будет проигнорирован. (Ранее предлагалось как @hide, но термин "скрыть" более уместен для динамическое шоу/скрытие во время выполнения возможности.) Для более подробного обсуждения см.: Запрос функции # 4058216 в Developer Подключение.

Ответ 2

См. соответствующий Запись в Javadoc FAQ.

В настоящее время нет опции Javadoc скрывать, исключать или подавлять членов из генерируемого javadoc документация.

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

Ответ 3

Не исключает ли что-то публичное из вашей документации только вариант "безопасность через безвестность" (точнее, "документация через неясность" )? Если конструктор является частью вашего API кода, он доступен для них. Если они узнают об этом и используют его, это их вина (поскольку вы сделали это публично в первую очередь)?

Если вы можете изменить видимость конструктора или вообще удалить его, я бы пошел на это. Если вы не можете удалить его из API, сообщите в Javadoc для конструктора, что он не предназначен для использования через веб-службу. Таким образом, вы создали контракт с пользователями вашего API, сообщив им, чтобы они не использовали его.

Лучше документировать, что его нельзя использовать вместо того, чтобы не документировать его вообще (если оно открыто). Не документируя это, добавляется риск, что он случайно используется, а затем код клиента, использующий его, ломается при изменении реализации.

Ответ 4

Измените уровень доступа к методу метода, затем используйте атрибуты фильтрации уровня доступа на уровне javadoc, private, package и т.д. Только сделайте это, если это имеет смысл в вашем коде, например, метод, который имел ненадлежащие уровни доступа.

Для конструкторов, например, вы можете снизить уровень доступа до package, а затем создать класс factory в том же пакете, который обеспечивает доступ к конструкции вне пакета. Класс factory можно легко фильтровать из javadocs. Вид хаки, но он работает.

Ответ 6

В настоящее время самым простым решением является запуск комментария javadoc с помощью @deprecated, а затем передача -nodeprecated в команду javadoc. Конечно, это может быть неприемлемо, если у вас есть фактические устаревшие элементы, которые вы, тем не менее, хотите включить в документацию.

Ответ 7

Закрытие, которое я получил, это использовать Doclava, который имеет тег @hide, который вы можете указать в документации по методу.