JEP 299: Reorganize Documentation

Аннотация

Обновить организацию документов в JDK как в репозиториях исходного кода, так и в генерируемой документации.

Цели

• Формально определить организацию генерируемого образа «docs», в который будут входить спецификации API, «страницы man» (их можно считать спецификациями инструментов) и другие спецификации JDK.
• Объединить нынешние более чем 20 наборов документации, генерируемых инструментом javadoc, в единое собрание спецификаций API для образа JDK.
• Определить организацию спецификаций, не относящихся к API, в репозиториях исходного кода так, чтобы их можно было при необходимости обновлять вместе с исходным кодом и легко включать в генерируемый образ «docs».

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

• Целью не является (это прямо противоположно цели) изменение каких-либо процессов или процедур, по которым принимается решение об обновлении спецификаций. Это касается и спецификаций JCP, например спецификаций API, и связанных с ними стандартов.
• Целью не является включение в эту работу всех спецификаций. Например, JLS и JVMS в это предложение не входят.
• Целью не является поддержка документации, которая не является спецификацией.
• Хотя цель состоит в том, чтобы определить организацию, в которую могут вписаться страницы man, предоставление страниц man для JDK 9 целью не является.

Мотивация

Сейчас стандартная сборка цели «docs» в JDK запускает инструмент javadoc более 20 раз (22 раза в Linux, 25 раз в Solaris) и генерирует соответствующее число разных наборов документации, организованных без какой-либо явно различимой системы. Хотя в документации javadoc теперь есть функция «Search», из-за нескольких наборов документации нельзя легко выполнить поиск сразу по всей предоставленной документации.

Ниже приведён список текущего собрания наборов документации; каждая запись соответствует отдельному запуску инструмента javadoc. Первая запись (api) знакома большинству: это спецификация платформы Java SE.

api
jdk/api/attach/spec
jdk/api/dynalink
jdk/api/javac/tree
jdk/api/javadoc/doclet
jdk/api/javadoc/old/doclet
jdk/api/javadoc/old/taglet
jdk/api/jconsole/spec
jdk/api/jlink
jdk/api/jpda/jdi
jdk/api/jshell
jdk/api/nashorn
jre/api/accessibility/jaccess/spec
jre/api/management/extension
jre/api/net/httpserver/spec
jre/api/net/socketoptions/spec
jre/api/nio/sctp/spec
jre/api/plugin/dom
jre/api/plugin/jsobject
jre/api/security/jaas/spec
jre/api/security/jgss/spec
jre/api/security/smartcardio/spec

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

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

Сейчас эти запуски инструмента javadoc управляются логикой в файлах make/common/CORE_PKGS.gmk и make/common/NON_CORE_PKGS.gmk. Обновлять эти файлы легко с ошибками, а иногда о них забывают. Например, сейчас есть четыре поддерживаемых пакета, которые не входят ни в какую публичную документацию. Лучше было бы автоматически получать список документируемых пакетов из списка пакетов, экспортируемых документируемыми модулями. Тогда всякий раз, когда новый пакет указывается как экспортируемый из модуля, он автоматически включался бы в любую документацию, в которую входит документация этого модуля.

Кроме того, OpenJDK не предоставляет «страницы man» для своих инструментов, хотя их можно считать спецификацией командной строки инструментов. Было бы хорошо включить такие спецификации в репозитории, чтобы при необходимости их можно было обновлять вместе с соответствующими инструментами, а соответствующие страницы генерировать и размещать чётко определённым образом в общем комплекте документации. То же относится к различным дополнительным спецификациям, например JNI Specification или Javadoc Tag Specification, у которых сейчас нет чётко определённого места.

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

Описание

Объединённая документация API

Для объединения генерируемой документации API нужно изменить make-файлы так, чтобы определять модули, содержащие документируемый API, и генерировать комплект со всеми модулями, у которых должен быть задокументирован весь экспортируемый API. Если это не покрывает всю генерируемую сейчас документацию API, нам следует определить организацию дополнительных наборов документации. Например, определить, что разные наборы находятся на одном уровне в единственном каталоге верхнего уровня «api».

docs/api/<doc-set>/

<doc-set> должно быть общим именем, описывающим соответствующее содержимое, например «jdk» или «java.se».

«Страницы man»

Исходный код в репозитории JDK обычно организован так:

src/<module-name>/{share,<os-name>}/{classes,native,...}

Предлагается дополнить последний такой компонент новым вариантом:

src/<module-name>/{share,<os-name>}/man

Каталог man должен содержать исходные файлы страниц man для инструментов объемлющего модуля. Такие файлы должны использовать синтаксис Markdown и называться по соответствующему инструменту. Например, исходный файл страницы man для инструмента javac должен находиться в src/jdk.compiler/share/man/javac.md.

Система сборки должна генерировать соответствующие файлы в новом каталоге верхнего уровня внутри генерируемого каталога docs. Генерируемые файлы могут быть в формате HTML или в формате «man» для систем, которые его поддерживают. Например, сгенерированная страница man для инструмента javac может находиться в

docs/man/javac.html
docs/man/man1/javac.1

Дополнительные спецификации

У некоторых модулей могут быть дополнительные связанные спецификации, которые иначе не входят в спецификации API или страницы man. Например, документационные комментарии обычно пишутся по «Javadoc Tag Specification», которую следует обновлять вместе с обновлениями инструмента javadoc. (Сейчас она доступна в Javac Tool Guide по довольно трудно запоминаемому адресу [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDFCBAD])

Вот некоторые дополнительные спецификации, которые можно рассмотреть для включения:

• JavaBeans spec
• Input Methods Framework Specification
• Jar File Specification
• Java Native Interface Specification
• Java Remote Method Invocation

Такие спецификации следует размещать в ещё одном новом каталоге, относящемся к модулю:

src/<module-name>/{share,<os-name>}/specs

Файлы из такого каталога должны копироваться в каталог specs внутри генерируемого каталога docs, за исключением файлов Markdown (.md), которые должны преобразовываться в файлы HTML. Если спецификация состоит из нескольких файлов, рекомендуется сгруппировать все файлы в подходящем подкаталоге.

Указатель

Сборка должна генерировать простой минимальный файл верхнего уровня index.html, содержащий ссылки на каждый элемент общей генерируемой документации. Этого должно хватать для простой навигации в базовой сборке «docs», но при подготовке более богатого комплекта документации этот файл можно при необходимости перезаписать.

Форматы

Файлы HTML должны быть в формате HTML 5 или HTML 4.01 и должны проходить проверку валидаторами, такими как tidy, а также средствами проверки ссылок и доступности. Со временем нам следует перевести все старые файлы HTML на HTML 5, поскольку в нём поддерживаются возможности, связанные с доступностью.

Файлы Markdown должны быть в одном из следующих форматов: Markdown; CommonMark; или Github Flavored Markdown, который предоставляет полезные расширения для списков определений, таблиц и подсветки синтаксиса в блоках кода.

Инструменты

Предлагается использовать инструмент с открытым исходным кодом pandoc для преобразования файлов Markdown в HTML или в формат страниц man (groff). Это означает появление новых зависимостей сборки от инструментов. pandoc поддерживает все варианты Markdown, перечисленные в предыдущем разделе.

Итоги

Новые подкаталоги исходного кода:

src/<module-name/{share,<os-name>}/
    man
    specs

Новый каталог генерируемой документации:

docs/
    api/
        <doc-set-1>
        <doc-set-2>
        etc
    man/
        <HTML man pages>
        man1/
            <man pages in man format>
    specs/
        <HTML spec pages>
        <directories for multi-file specifications>