Selective API Javadocs

Question

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

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

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

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

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

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

Answer 1

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

Для получения более подробной информации обратитесь к javadoc command line synopsis.

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

Answer 2

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

Скажите, что у вас есть 5 классов, и вы хотите, чтобы только классы в 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 

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

Опубликовано здесь для ясности: Javadoc Documentation

Answer 3

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

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

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

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

Answer 4

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

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

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