Существует относительно старая веб-страница под названием « Предложенные теги Javadoc », которая, кажется, изначально была написана вместе с Javadoc 1.2, в которой перечислены «теги, которые Sun может реализовать в Javadoc когда-нибудь». @category в этом списке являются @category , @example , @tutorial , @index , @exclude , @todo , @internal , @obsolete и @threadsafety . Один из этих тегов, @index , переместился из «Предложенных тегов» в «Стандартные теги» с его включением в Java 9. В документации по инструменту Java 9 Javadoc указано, что тег @index используется для указания индексированного «поискового термина или фразу », которую можно искать в новой функции поиска Javadoc в Java 9 .
Возможность добавлять термины для поиска в сгенерированной Javadoc документации желательна в течение некоторого времени, о чем свидетельствует наличие JDK-4034228 («stddoclet: добавить тег @index doc-comment для создания индекса из общих слов»), JDK-4279638 («Комментарии Javadoc: нужна возможность пометить слова для включения в индекс API») и JDK-4100717 («Разрешить пользовательские записи индекса»). JEP 225 («Поиск Javadoc») использовался для «добавления поля поиска к документации API, сгенерированной стандартным доклетом, который можно использовать для поиска элементов программы, а также теговых слов и фраз в документации».
Javadoc в Java 9 и более поздних версиях автоматически будет включать в конструкцию «Поиск» несколько конструкций, которые можно выполнить из сгенерированного вывода HTML. По умолчанию для поиска доступны строки, основанные на именах методов, именах членов, именах типов, именах пакетов и именах модулей. Преимущество, предлагаемое @index заключается в том, что фразы или поисковые термины, не встроенные в имена этих только что перечисленных конструкций, могут быть явно указаны в искомом индексе.
Есть несколько примеров того, как может быть полезна возможность добавления настраиваемого текста для поиска документации, сгенерированной Javadoc. Документация по инструменту Javadoc ссылается на «специфичный для домена термин ulps» (« единицы в последнем месте ») и объясняет, что хотя « ulps используется во всем классе java.lang.Math », он «не появляется ни в одном классе или имена объявлений методов ». Использование @index позволило бы разработчикам API класса Math добавить « ulps » в индекс с возможностью поиска, чтобы помочь людям найти класс Math при поиске «ulps». В третьем издании Effective Java Джош Блох ссылается на еще один пример того, где Javadoc {@index} может быть полезен. В {@index IEEE 754} 56 Блох приводит пример, используя {@index IEEE 754} (« Стандарт IEEE для арифметики с плавающей точкой »).
Недавно я столкнулся с делом в JDK, где я думал, что использование {@index} будет уместным. Недавно я опубликовал информацию о двойной сводной сортировке, но понял, что при поиске в выводе, сгенерированном Javadoc, не найдено совпадений для этого термина. Похоже, было бы полезно добавить такие термины, как «Двойная сводная сортировка» и «Слияние» в поисковый индекс Javadoc через {@index} .
К сожалению, наличие пробелов в тексте, встроенных в тег {@index } похоже, приводит к тому, что только термины перед первым пробелом отображаются в отображаемом HTML (и являются единственными частями, которые можно искать). Чтобы продемонстрировать это, следующий нелепо придуманный код Java содержит три {@index} Javadoc {@index} представляющих три только что рассмотренных примера.
Java-код, использующий {@index} в своей документации
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
|
package dustin.examples.javadoc;/** * Used to demonstrate use of JDK 9's Javadoc tool * "@index" tag. */public class JavadocIndexDemonstrator{ /** * This method complies with the {@index IEEE 754} standard. */ public void doEffectiveJava3Example() { } /** * Accuracy of the floating-point Math methods is measured in * terms of {@index ulps}, "units in the last place." */ public void doMathUlpsExample() { } /** * This method uses a version of the {@index Dual-Pivot Quicksort}. */ public void doDualPivotQuicksort() { }} |
Когда инструмент Javadoc выполняется с кодом выше на моем компьютере с Windows 10 в Java 9.0.4, сгенерированная HTML-страница выглядит следующим образом:
«754» отсутствует в сгенерированном HTML после «IEEE», а «Quicksort» отсутствует после «Dual-Pivot» в документации методов. В следующем листинге кода показан сгенерированный исходный код HTML для этих частей с отсутствующим текстом.
HTML Source
|
1
2
3
|
<div class="block">This method uses a version of the <a id="Dual-Pivot" class="searchTagResult">Dual-Pivot</a>.</div> . . .<div class="block">This method complies with the <a id="IEEE" class="searchTagResult">IEEE</a> standard.</div> |
Из только что показанного HTML-кода становится понятно, почему только текст перед первым пробелом появляется на странице и доступен для поиска. Атрибут «id», связанный с классом «searchTagResult» для каждой записи с возможностью поиска, состоит из строки с возможностью поиска. Поскольку атрибуты HTML «id» не могут иметь пробелов , только символы до первого пробела могут использоваться для значения «id».
Поскольку в атрибутах «id» не допускаются пробелы, необходимо использовать один из следующих обходных путей при работе с несколькими словами в одной фразе, для которой требуется поиск.
- Удалить пробелы
- «{@Index IEEE 754}» становится «{@index IEEE754}»
- «{@Index Dual-Pivot Quicksort}» становится «{@index Dual-PivotQuicksort}»
- Замените пробелы допустимым символом (например, дефис)
- «{@Index IEEE 754}» становится «{@index IEEE-754}»
- «{@Index Dual-Pivot-Quicksort}» становится «{@index Dual-Pivot-Quicksort}»
- Используйте отдельный
{@index}для каждого слова в фразе- «{@Index IEEE 754}» становится «{@index IEEE} {@index 754}»
- «{@Index Dual-Pivot Quicksort}» становится «{@index Dual-Pivot} {@index Quicksort}»
- Используйте
{@index}только в наиболее важных словосочетаниях- «{@Index Dual-Pivot Quicksort}» становится «{@index Dual-Pivot} Quicksort»
- Представляет фразу из нескольких слов с общим представлением одного слова
- Вот почему «ulps» в документации по инструменту Javadoc работает лучше, чем «единицы на последнем месте».
Раздел «Мотивация» в JEP 225 («Поиск по Javadoc») хорошо описывает преимущества этой возможности поиска терминов в Javadoc:
На страницах документации API, созданных стандартным доклетом, может быть сложно ориентироваться, если вы еще не знакомы с их макетом. Можно использовать внешнюю поисковую систему, но это может привести к устаревшей или неактуальной странице. Можно использовать встроенную в браузер функцию поиска, но она ограничена поиском по текущей странице, а не по всему объему документации.
Хотя добавление возможности поиска в сгенерированную Javadoc документацию является незначительным дополнением в Java 9, ее можно использовать, чтобы сделать документацию своего кода Java более полезной для других разработчиков и пользователей этого кода.
| Опубликовано на Java Code Geeks с разрешения Дастина Маркса, партнера нашей программы JCG . См. Оригинальную статью здесь: Добавление терминов в поиск Javadoc с помощью Java 9
Мнения, высказанные участниками Java Code Geeks, являются их собственными. |