JDK 10 вводит тег Javadoc {@summary} выпуске JDK-8173425 («Javadoc нужен новый тег для указания сводки».). Этот новый тег позволяет разработчику явно указывать, какая часть комментария Javadoc появляется в «сводке», вместо того, чтобы полагаться на стандартную обработку Javadoc для поиска точки и пробела, чтобы разграничить конец итоговой части комментария. В JDK-8173425 говорится: «В настоящее время в javadoc сводка (firstsentence) элемента расшифровывается правилом точечного пространства или, если требуется, с помощью BreakIterator». Он добавляет, что может быть непонятно, каким будет это неявно выбранное краткое предложение.
Самый простой способ увидеть {@summary} в действии — это примеры Javadoc. В следующем листинге кода показаны четыре метода с похожими комментариями Javadoc, два из которых используют явные теги {@summary} а два используют неявную конструкцию сводки Javadoc.
Демонстрация {@summary} в комментариях метода Javadoc
|
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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
|
package dustin.examples.javadoc;/** * Demonstrate JDK 10 added summary support. Demonstrates * this by comparing similar methods' Javadoc comments with * and without use of new "@summary" tag. */public class Summary{ /** * This method's first sentence is normally in the summary. * Here are some of its characteristics: * <ul> * <li>This method does great things.</li> * <li>This method does not really do anything.</li> * </ul> */ public void implicitSummary1() { } /** * This method's first sentence is normally in the summary.Here are some of its characteristics: * <ul> * <li>This method does great things.</li> * <li>This method does not really do anything.</li> * </ul> */ public void implicitSummary2() { } /** * {@summary This method's first sentence is normally in the summary. * Here are some of its characteristics: * <ul> * <li>This method does great things.</li> * <li>This method does not really do anything.</li> * </ul>} */ public void explicitSummary1() { } /** * {@summary This method's first sentence is normally in the summary.Here are some of its characteristics: * <ul> * <li>This method does great things.</li> * <li>This method does not really do anything.</li> * </ul>} */ public void explicitSummary2() { }} |
Когда инструмент Javadoc, поставляемый с первым JDK 10 (18.3) Release Candidate (Build 43) , выполняется для этого простого класса, раздел « Сводка метода » сгенерированного HTML выглядит следующим образом в веб-браузере.
Сравнивая вывод HTML с прокомментированным Java-кодом выше, он демонстрирует, как {@summary} позволяет явно контролировать то, что появляется в сводках методов.
| Опубликовано на Java Code Geeks с разрешения Дастина Маркса, партнера нашей программы JCG . Смотрите оригинальную статью здесь: JDK 10’s Javadoc Tag
Мнения, высказанные участниками Java Code Geeks, являются их собственными. |