Как Javadoc имеет дело с видимостью модулей в Java 9?

Инструмент Javadoc создает документацию на основе модификатора доступности. По умолчанию он документирует все классы, поля и методы public и protected. Это можно изменить с помощью следующих параметров:

-публичный
Показывает только публичные классы и участники.

-защищенного
Показывает только защищенные и общедоступные классы и участники. Это значение по умолчанию.

-package
Показывает только пакетные, защищенные и общедоступные классы и члены.

-private
Показывает все классы и участники.

Java 9 представляет концепцию модулей, а проект Jigsaw применяет ее к существующему JDK. A talk от Марка Рейнхольда (третий в серии разговоров о модулях) показывает, как модификатор public теперь имеет разные уровни доступности, в зависимости от видимости модуля (через exports):

  • для всех
  • общедоступный, но только для определенных модулей
  • публикация только внутри модуля

Поскольку теперь доступны не все публичные члены, было бы бессмысленно продолжать с той же схемой генерации Javadoc. Следует документировать только участников, которые подвергаются воздействию "достаточного" уровня.

Является ли модуль Javadoc осведомленным? Есть ли опции команды в дополнение к описанным выше для обработки дополнительного уровня экспозиции? Для публичных участников, которые отображаются только для определенных модулей, перечисляет ли Javadoc эти, как в

public <module1, module2> static void getDefaultThing()

?

Ответы

Ответ 1

В javadoc есть новые параметры, которые позволяют вам выбирать, какие элементы задокументированы в модуле, пакете, типе и уровне участника. Используя версию EA JDK 9, найдите новые опции --module, --show-* и --expand-requires.

Существующие параметры -public, -protected, -package, -private были переопределены с точки зрения новых опций --show-*, хотя их помощь в командной строке все еще нуждается в обновлении.

Таблица преобразования удобных денди:

-public
      --show-module-contents api --show-packages exported --show-types public --show-members public

-protected   (the long-standing default)
      --show-module-contents api --show-packages exported --show-types protected --show-members protected

-package
      --show-module-contents all --show-packages all --show-types package --show-members package

-private
      --show-module-contents all --show-packages all --show-types private --show-members private

В общем, продолжайте использовать по умолчанию для создания документации для пользователей API и, возможно, используйте -package или -private для создания документации для разработчиков API. Для более мелкого контроля используйте базовые параметры --show-*.