JEP 172: DocLint

Аннотация

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

Цели

Сейчас инструмент javadoc почти не проверяет содержимое комментариев Javadoc, а те проверки, которые он всё же выполняет, не связаны с исходным кодом, и разработчики обычно не обращают на них внимания. В результате ошибки, как правило, попадают в сгенерированные файлы документации и могут затронуть спецификации в этих файлах. Нам нужны более совершенные инструменты, которые помогут обнаруживать больше ошибок и раньше, так чтобы найденные проблемы было легко исправить.

Типичные ошибки можно разделить на несколько категорий:

• Неправильный синтаксис, например неэкранированные символы («<») или непарные скобки («{@foo»)
• Неправильный HTML, например недопустимые или отсутствующие теги или атрибуты
• Неправильные ссылки, например ссылка на несуществующий тип в @see или на несуществующий параметр в @param
• Ошибки доступности, например отсутствие summary или caption у таблицы
• Недостающая информация, например недокументированный параметр

Цель — обнаруживать и сообщать о большинстве распространённых ошибок, которые допускают разработчики при написании комментариев Javadoc, так чтобы сгенерированные выходные файлы в целом проходили проверку внешними инструментами валидации, например инструментами проверки соответствия HTML и требованиям доступности.

Обо всех ошибках следует сообщать так же, как это делают распространённые компиляторы, чтобы сообщения могли легко обрабатываться подходящими редакторами и IDE и разработчики могли легко находить и исправлять ошибки.

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

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

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

Мотивация

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

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

Сегодня принято считать важным, чтобы сгенерированная документация соответствовала рекомендациям по доступности, например Section 508. Нам нужны более совершенные инструменты, которые помогут обнаруживать вероятные ошибки на том этапе цикла разработки, когда такие проблемы легко исправить.

Существующие формальные инструменты, например средства проверки соответствия HTML и требованиям доступности, можно применять только к выводу инструмента javadoc. Из-за этого трудно соотнести сообщения об ошибках с местом в исходном тексте. Нам нужны инструменты, которые могут сообщать об ошибках в контексте исходного кода.

Описание

Инструмент будет построен на основе «DocTree API», описанного в JEP 105, который сам является расширением javac «Tree API», теперь доступного в пакете com.sun.source. DocTree API позволяет получить «синтаксическое дерево» для элементов комментария Javadoc.

Инструмент будет сканировать исходные файлы в поиске объявлений, у которых есть связанные комментарии Javadoc. Он будет разбирать эти комментарии с помощью DocTree API, а затем анализировать полученное AST в поиске проблем.

Инструмент можно предоставить несколькими способами.

1. Поскольку инструмент обрабатывает комментарии Javadoc, естественно было бы представить его как doclet. Пользователь указывал бы использование doclet в командной строке javadoc с помощью существующих параметров javadoc -doclet и -docletpath. Doclet предоставлял бы дополнительные параметры для выбора категорий проблем, о которых нужно сообщать, аналогично существующему параметру javac -Xlint.

   Вариант этого способа — «жёстко встроить» инструмент в существующий стандартный doclet. Так пользователю будет проще вызывать инструмент, но это означает потерю производительности, поскольку стандартный doclet пока не использует DocTree API. (Это была бы достойная цель для отдельного проекта.) Однако javadoc и так работает медленно (!!), а разбор комментариев с помощью DocTree API выполняется быстро, поэтому заметное замедление может оказаться не слишком обременительным.

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

2. Инструмент можно предоставить как новый отдельный инструмент. Это потребует дополнительной работы, например создания средства запуска и соответствующих man-страниц. Прежний опыт с инструментом обработки аннотаций apt показал, что внедрить новый инструмент в типичную цепочку инструментов разработчика трудно.

3. Инструмент можно «подключить» к javac, так чтобы разработчик мог по желанию видеть сообщения о проблемах в комментариях Javadoc одновременно с сообщениями о проблемах в своём исходном коде. Тогда включить инструмент будет так же просто, как добавить ещё один параметр в командную строку javac. Поскольку у инструмента будут собственные параметры настройки, его использование — не выбор «да/нет», который можно добавить в существующий механизм javac -Xlint. Вместо этого предлагается, чтобы инструмент использовал похожий, но другой параметр: -Xdoclint или -Xdoclint:args.

4. Инструмент также можно подключить к IDE, например NetBeans, которая уже использует вариант javac для вывода информации об ошибках в окне редактора исходного кода. Изменение редактора исходного кода NetBeans выходит за рамки этой работы, но инструмент не должен мешать кому-либо ещё интегрировать его в IDE, так чтобы «красные волнистые линии» в комментариях Javadoc появлялись не только для орфографических ошибок.

Ожидается, что мы реализуем некоторое сочетание способов 1 и 3, сделав инструмент доступным через javac и javadoc.

Альтернативы

Задачу обеспечения корректного HTML-вывода инструмента javadoc можно было бы решить полуавтоматической постобработкой вывода с помощью инструмента вроде htmltidy. Однако генерация «чистого» HTML из некорректных входных данных просто скрывает проблему и не помогает решить основную задачу — найти (и исправить) ошибки в исходном тексте.

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

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

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

Если эта возможность должна войти в JDK 8, основной риск — наличие ресурсов. План снижения риска — пока предоставить инструмент отдельно, чтобы включить его в более поздний выпуск платформы.

Зависимости

Зависит от JEP 105, который теперь доступен в JDK 8, сборка 66 (M5).

Влияние

• Доступность: поможет улучшить доступность сгенерированной нами документации
• Документация: поможет улучшить соответствие сгенерированной нами документации стандартам HTML.