JEP 224: HTML5 Javadoc

HTML5 в Javadoc

Ответственный	Bhavesh Patel
Тип	Feature
Область	JDK
Статус	Closed / Delivered
Выпуск	9
Компонент	tools / javadoc(tool)
Обсуждение	javadoc dash dev at openjdk dot java dot net
Трудоёмкость	M
Длительность	M
Рецензенты	Jonathan Gibbons
Одобрен	Brian Goetz
Создан	2014/06/05 20:00
Обновлён	2018/04/13 08:16
Задача	8046068

Аннотация

Доработать инструмент javadoc, чтобы он генерировал разметку HTML5.

Цели

Добавить в стандартный doclet параметр, с помощью которого можно запросить вывод в формате HTML 4 или HTML5. Разметка HTML5 семантическая, то есть в ней смысл чётко отделён от стиля и содержимого. Части страниц, которые стандартный doclet генерирует с разметкой HTML5, соответствуют требованиям доступности.

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

Заменить текущую структуру генерируемых HTML-страниц (с тремя фреймами или без фреймов) не является целью. Это может стать предметом будущего JEP.

Целью не является обязательное использование HTML5 в документирующих комментариях. Также не является целью возможность преобразовывать документирующие комментарии, написанные на HTML 4, в HTML5.

Мотивация

В JDK 8 и более ранних выпусках стандартный doclet генерировал страницы в формате HTML 4.01. Это старый стандарт, и он не позволяет выполнить требования доступности.
HTML5 — последний стандарт HTML. HTML5 повышает семантическую ценность веб-страниц и упрощает создание доступных веб-страниц.

Описание

В стандартный doclet добавляется параметр командной строки, с помощью которого можно запросить определённый тип выходной разметки. По умолчанию будет использоваться HTML4, текущий тип. В JDK 10 HTML5 станет вариантом по умолчанию.
Семантическая ценность генерируемого HTML повышается за счёт структурных элементов HTML5, таких как header, footer, nav и т. д.
Разметка HTML5 реализует стандарт WAI-ARIA для доступности. Элементам HTML-документа назначаются определённые роли с помощью атрибута role.
Функция -Xdoclint обновлена: теперь она проверяет документирующие комментарии на типичные ошибки с учётом запрошенного типа выходной разметки.

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

Предусмотрены тесты, которые проверяют, что:

разметка HTML5 корректна;
разметка HTML5 соответствует требованиям доступности;
новый параметр командной строки работает правильно;
разметка HTML5 работает во всех поддерживаемых браузерах.

Из-за отсутствия автоматизированных инструментов проверки доступности сложно провести всестороннее тестирование доступности. Репрезентативную выборку страниц разных типов можно проверить с помощью онлайн-инструментов.