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

Question

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

Answer 1

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

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

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

Answer 2

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

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

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

Answer 3

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

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

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

Answer 4

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

Answer 5

Попробуйте ExclusiveDoclet Криса Ноклеберга: http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html

Я только что экспериментировал с этим, и, похоже, он добился цели.

Answer 6

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

Например, для конструкторов вы можете снизить уровень доступа до package, а затем создать фабричный класс в том же пакете, который обеспечивает доступ к конструкции вне пакета. Фабричный класс может быть легко отфильтрован от Javadocs. Отчасти хакерский, но он работает.

Answer 7

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