JEP 221: New Doclet API

Аннотация

Предоставить замену для Doclet API, использующую подходящие API из Java SE и JDK, и перевести стандартный doclet на новый API.

Примечание

В этом документе термин «старый Doclet API» обозначает API в com.sun.javadoc, а «старый стандартный doclet» — com.sun.tools.doclets.standard.Standard.

Термин «новый Doclet API» обозначает API в jdk.javadoc.doclet, а «новый стандартный doclet» — jdk.javadoc.doclet.StandardDoclet.

Цели

• Снизить затраты на сопровождение устаревших API.

• Отказаться от собственного API модели языка в пользу стандартного API модели языка javax.lang.model, появившегося в Java SE 6.

• Отказаться от упрощённой поддержки анализа документирующих комментариев в пользу Compiler Tree API com.sun.source.doctree, появившегося в JDK 8.

• Заменить использование «шаблонного класса» com.sun.javadoc.Doclet подходящим новым интерфейсным типом.

Что не является целью

Хотя повышение производительности не является целью, ожидается, что в результате этой работы производительность инструмента javadoc и нового стандартного doclet улучшится.

Мотивация

У старых Doclet API есть следующие проблемы, которые необходимо решить.

• API определяет doclet просто как класс, реализующий некоторые или все методы из набора статических методов, как показано на примере шаблонного класса com.sun.javadoc.Doclet. Использование статических методов особенно неудобно, поскольку для обмена данными между методами приходится использовать статические члены. Это плохо сказывается как на конкурентном использовании, так и на тестировании.

• API предоставляет собственный API модели языка, у которого есть ряд ограничений (например, массивы моделируются плохо) и который трудно обновлять по мере развития языка Java в тех направлениях, которые затрагивают сигнатуры API (например, обобщённые типы, аннотации типов и методы по умолчанию).

• API предоставляет минимальную, неэффективную и не полностью специфицированную поддержку анализа содержимого документирующего комментария. Это создаёт значительную нагрузку на любой doclet, которому нужно обрабатывать содержимое комментария. Кроме того, API никак не позволяет определить позицию конструкций внутри комментария в содержащем его исходном файле. Из-за этого фактически невозможно указать точное положение для любой диагностики, о которой следует сообщить. Поддержка анализа комментариев опирается на плохую и неэффективную реализацию в старом стандартном doclet, которая во многом полагается на сопоставление подстрок для разделения конструкций внутри комментария.

Описание

Новый Doclet API объявлен в пакете jdk.javadoc.doclet. Он использует Language Model API и Compiler Tree API.

Инструмент javadoc обновлён так, чтобы распознавать doclet, написанные с использованием нового Doclet API. Старые Doclet API будут поддерживаться на переходный период и будут заморожены, то есть не будут обновляться для поддержки новых возможностей языка, появившихся в течение переходного периода.

Существующий стандартный doclet поддерживает дополнительный API подключаемых модулей, известный как Taglet API. С помощью taglet пользователи могут определять собственные теги, которые можно использовать в документирующих комментариях, и задавать, как такие теги должны выглядеть в сгенерированной документации. Обновлённый стандартный doclet поддерживает обновлённый API для taglet.

Риски и допущения

Кроме того, старый Doclet API, который в настоящее время является поддерживаемым API, получил статус Deprecated (устаревший) и может быть удалён в одном из будущих выпусков. Пользователям старого Doclet API рекомендуется перевести свой код на новый Doclet API.

Известно, что некоторые существующие doclet, написанные пользователями, напрямую обращаются к коду внутри старого «стандартного doclet», хотя этот код не является (и никогда не являлся) поддерживаемым интерфейсом. Поскольку этот код трудно сопровождать и обновлять, особенно с учётом недавних новых возможностей языка, старый «стандартный doclet» в JDK 9 получил статус Deprecated for Removal (устаревший, будет удалён) и будет удалён в одном из будущих выпусков.

Тестирование

Существующий набор тестов для Doclet API и стандартного doclet адаптирован для тестирования нового API и нового стандартного doclet. Добавлены дополнительные тесты для граничных случаев.