Селективный API Javadocs

Question

У меня есть то, что, безусловно, должно быть достаточно распространенной документацией ...

Я реализую довольно значительную базу кода библиотеки Java, которая, помимо прочего, имеет различные классы, предназначенные для предоставления вызывающей стороне / разработчику на соответствующем уровне абстракции. В то же время кодовая база содержит, конечно, различные внутренние классы, интерфейсы и другие абстракции, о которых пользователю библиотеки не нужно знать, чтобы использовать API.

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

Я не хочу быть в том же положении. Я хотел бы иметь «внутренний» набор Javadocs, который раскрывает весь экстент кодовой базы, и «внешний» набор Javadoc, предназначенный для того, чтобы четко сообщать разработчикам характеристики классов, которые им действительно нужны для получения своих работа сделана. Мне не нужно или не хочется мутить воду различными внутренними абстракциями, которые они не должны видеть или знать о них - им не нужно знать, как все это работает под капотом, и это только запутает и дезинформирует их , что делает процесс обучения API очень неэффективным.

Как мне это сделать? Существует ли общеизвестная комбинация аргументов для javadoc и, возможно, некоторые аннотации, которые могут это сделать?

Большое спасибо за внимание!

Answer 1

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

Подробнее см. в командной строке javadoc.

(Если вы не организовали свои пакеты так, чтобы внутренние классы не входили в пакеты API, вам может быть немного больно ...)

Answer 2

В дополнение к ответу Стивена С. и с помощью инструмента javadoc вы можете точно указать, какие пакеты появляются в javadoc (отсюда и комментарий Стивена С. о «боли», если они не организованы логически), используя что-то вроде этого: 1002 *

Допустим, у вас есть 5 классов, и вы хотите, чтобы в Javadoc отображались только классы из пакета org.notprivate:

org.notprivate.Foo
org.notprivate.Bar
org.notprivate.Stuff
org.notpublic.Things
org.notpublic.More

Вы можете использовать что-то вроде:

javadoc -d target/api -source 1.6 -sourcepath src/main/java org.notprivate

Это только быстрый пример, если вам нужно указать каждый класс, вам нужно взглянуть на ссылку Стивена С, предоставленную более подробно

Размещено здесь для ясности: Документация Javadoc

Answer 3

Я хотел бы иметь ... «внешний» набор Javadoc, предназначенный для того, чтобы четко сообщать разработчикам характеристики классов, которые им действительно нужно использовать для выполнения своей работы. Мне не нужно или не хочется мутить воду различными внутренними абстракциями, которые они не должны видеть или знать о них - им не нужно знать, как все это работает под капотом, и это только запутает и дезинформирует их , что делает процесс обучения API очень неэффективным.

Учитывая это желание, возможно, Javadoc не лучший способ документирования общего представления системы или предоставления информации типа «вот что вам нужно знать» новым разработчикам?

Я бы порекомендовал дополнить ваши файлы Javadoc отдельным руководством / document / wiki / что-то, чтобы дать мета-представление.

Answer 4

Вы можете использовать некоторые дополнительные аргументы при вызове инструмента javadoc:

• -public: отображаются только публичные классы и участники.
• -защищенный: Показывает только защищенные и открытые классы и члены. Это значение по умолчанию.
• -package: Показывает только пакеты, защищенные и публичные классы и члены.
• -private: показывает все классы и членов.

Итак, с помощью этих опций вы можете создать полную документацию для внутреннего использования и предоставить «легкую» документацию только с открытым интерфейсом для ваших клиентов.

Если вы используете Eclipse, мастер Javadoc отображает переключатели, помогающие выбрать уровень документации - по умолчанию это «только открытые поля».