JEP 225: Javadoc Search

Аннотация

Добавить в документацию API, генерируемую стандартным doclet, поле поиска. Через него можно искать элементы программы, а также помеченные тегами слова и фразы в документации. Поле поиска находится в заголовке всех страниц, которые генерирует стандартный doclet.

Цели

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

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

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

Мотивация

В страницах документации API, которые генерирует стандартный doclet, бывает трудно ориентироваться, если вы ещё не знакомы с их компоновкой.
Можно воспользоваться внешней поисковой системой, но она может привести на устаревшую или не относящуюся к делу страницу. Можно воспользоваться встроенной функцией поиска браузера, но она ищет только на текущей странице, а не по всему набору документации.

Описание

Что можно искать?

• Объявленные имена модулей, пакетов, типов и членов индексируются, и по ним можно искать. Поскольку методы могут быть перегружены, простые имена типов параметров методов также индексируются, и по ним тоже можно искать. Имена параметров методов не индексируются.

• Можно искать поисковый термин или фразу, проиндексированные с помощью нового inline-тега @index. Другие inline-теги нельзя вкладывать внутрь @index. Искать можно только фразу или поисковый термин, помеченные @index в документационном комментарии объявления. Например, предметный термин «ulps» используется по всему классу java.lang.Math, но не встречается ни в одном имени класса или объявлении метода. Чтобы помочь пользователям Math API, проектировщик API может пометить тегом различные вхождения «ulps» в документационных комментариях на уровне класса или метода. Пометка выполняется с помощью {@index ulps}. «ulps» будет проиндексирован javadoc.

Формат и расположение генерируемого индекса со временем могут меняться, и другие инструменты не должны на них полагаться.

Подготовка к поиску

По умолчанию запуск javadoc генерирует индекс, благодаря которому в сгенерированном HTML может работать поле поиска. Результаты поиска формирует JavaScript на стороне клиента. С помощью опции -noindex для javadoc можно отключить индексирование и поиск. Как и в случае со всеми остальными файлами, которые могут генерироваться или не генерироваться, javadoc не удаляет устаревшие файлы в выходном каталоге. Пользователь сам отвечает за то, чтобы выходной каталог был пуст перед запуском javadoc, чтобы в нём не осталось устаревших файлов от предыдущих запусков.

Как искать

На сгенерированных страницах API есть поле поиска, которое предоставляет:

• Средство для запуска поиска по вводу пользователя. Поисковый ввод поддерживает поиск в стиле camel case. Например, чтобы найти метод addFocusListener(), пользователю достаточно ввести в поле поиска «addFL». Поисковый ввод не поддерживает регулярные выражения, хотя это может быть рассмотрено в дальнейшей работе.

• Результаты: сначала те, что точно совпадают с введёнными символами, затем те, что содержат введённые символы в любом месте строки. Несколько результатов отображаются простым прокручиваемым списком под полем поиска. Результаты разделены на категории «Modules», «Packages», «Types», «Members» и «Search Tags», чтобы их было проще классифицировать и чтобы пользователю было удобнее выбирать нужный; и

• Переход на страницу в соответствии с выбором пользователя.

Библиотеки

В реализации используются jQuery UI Autocomplete и JSZip, чтобы автодополнение работало независимо от браузера. Это функция на стороне клиента.

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

Тесты проверяют следующее:

• Точность поискового индекса
• Использование нового тега @index
• Точность выбора в автодополнении и перехода на страницу
• Защиту от вредоносных инъекций