checkstyle - Написание проверок Javadoc

  1. Что такое Javadoc комментарий Комментарий Javadoc - это многострочный комментарий / * * /, который...
  2. Жесткие правила HTML
  3. Как создать Javadoc Check
  4. Разница между грамматикой Java и комментариями Javadoc
  5. Инструмент для печати древовидной структуры Javadoc
  6. Доступ к Java AST из проверки Javadoc
  7. HTML-код в комментариях Javadoc
  8. Checkstyle SDK GUI
  9. Настройка типов токенов в проверках Javadoc
  10. Примеры проверок Javadoc
  11. Поведение анализатора Javadoc для текущей версии HTML и новой версии HTML

Что такое Javadoc комментарий

Комментарий Javadoc - это многострочный комментарий / * * /, который начинается с символа * и помещается над определением класса, определением интерфейса, определением перечисления, определением метода или определением поля. Если аннотация предшествует какому-либо из приведенных выше определений, то комментарий Javadoc следует поместить перед аннотацией. Если несколько многострочных комментариев с идентификаторами Javadoc размещаются последовательно, будет использоваться только один из них, ближайший к определению, прямо над ним, с идентификатором Javadoc.

Комментарии Javadoc должны содержать: краткое резюме (первое предложение), дополнительный раздел документации, дополнительный раздел тегов. Первое предложение имеет особое значение и должно быть четким, резким, коротким и заканчиваться символом точки. Сразу после первого предложения может начаться основное описание, за которым может следовать раздел тега. Раздел тега начинается с первого тега блока, который определяется первым символом @, начинающим строку (игнорируя начальные звездочки, пробел и начальный разделитель / **).

Например, вот файл Java:

/ ** * Мой <b> класс </ b>. * * @see Аннотация * / открытый класс MyClass {/ ** Не является Javadoc (игнорируется). * / / ** * Удваивает значение. * Длинное и подробное объяснение того, что делает метод. * * @param значение для удвоения. * @ return двойное значение. * / / * Многострочный комментарий (игнорируется). * / @Annotation / ** Дополнительный Javadoc (игнорируется). * / // Однострочный комментарий (игнорируется). метод public int (значение int) {/ ** Внутренний javadoc (игнорируется). * / возвращаемое значение * 2; }}

Контент Javadoc для MyClass будет:

Мой <b> класс </ b>. @ смотри аннотацию

Содержимое Javadoc для MyClass.method будет:

Удваивает значение. Длинное и подробное объяснение того, что делает метод. Значение @param для удвоения. @ вернуть двойное значение.

Обратите внимание, что Java-комментарий начинается с / *, затем идет Идентификатор типа комментария. Идентификатор Javadoc *. Все символы после идентификатора Javadoc до * / являются частью комментария Javadoc.

Обратите внимание, что javadoc-подобный (многострочный комментарий с идентификатором javadoc) внутри метода не является комментарием javadoc и пропускается инструментом javadoc Sun / Oracle и нашим средством сопоставления комментариев javadoc, но такой комментарий будет в AST.

В Интернете вы можете найти различные типы инструментов для создания документации, похожие на javadoc. Такие инструменты зависят от конкретного идентификатора: "!", "#", "$". Комментарии выглядят как "/ *! Некоторые комментарии * /", "/ * # некоторые комментарии * /", "/ * $ некоторые комментарии * /". Такие многострочные комментарии не являются Javadoc.

Ограничения

По спецификации Javadoc может содержать любые теги HTML, которые позволяют пользователю создавать контент, который ему нужен. Все теги копируются в том виде, в каком они были получены в виде HTML-страниц javadoc, с помощью инструмента Sun / Oracle javadoc. Все плохое форматирование является ответственностью пользователя и веб-браузера. Чтобы проверить Checkstyle для анализа входных данных в предсказуемой структуре - Абстрактное синтаксическое дерево (AST). Очень сложно разобрать формат произвольного стиля, поэтому вводимый текст должен соответствовать какому-либо формату, поэтому появляются ограничения.

Комментарий должен быть написан на Плотно HTML построить вложенное дерево AST, которое ожидает большинство проверок.

Подробнее о разборе HTML в AST читайте HTML-код в комментариях Javadoc а также Поведение анализатора Javadoc раздел.

Жесткие правила HTML

Каждый HTML-тег должен иметь соответствующий конечный HTML-тег, или это пустой элемент ,

Единственными исключениями являются теги HTML 4, конечный тег которых является необязательным (опускаемым) в соответствии со спецификацией HTML (например, TR ), поэтому Checkstyle не будет отображать ошибку об отсутствии конечного тега, однако, это приводит к нарушению структуры Tight-HTML и, как результат, приводит к не вложенному содержимому тегов HTML в дереве абстрактного синтаксиса комментария Javadoc.
Другими словами, если HTML-теги не закрыты, грамматика Javadoc не может определить содержимое этих тегов, поэтому структура дерева разбора не будет вложенной, как во время использования. Плотно HTML код. Это сделано только для того, чтобы не потерпеть неудачу в каждом комментарии Javadoc, потому что есть множество использования незакрытых тегов и т. Д.

Другие правила:

  • Элементы структуры документа (DOCTYPE, <html>, <body> и т. Д.) Не являются обязательными.
  • Элементы должны быть всегда закрыты, за исключением элементов HTML4, конечный тег которых является необязательным (опускаемым) и HTML4 пустые элементы , Увидеть HTML-код в комментариях Javadoc раздел
  • Элементы HTML могут быть в нижнем или верхнем регистре
  • Имена атрибутов могут быть в нижнем или верхнем регистре
  • Значения атрибута могут быть заключены в кавычки или не заключены в кавычки

Как создать Javadoc Check

Принцип написания проверок Javadoc аналогичен написанию обычных проверок. Вы просто расширяете другой абстрактный класс и используете другие типы токенов.

Чтобы начать реализацию новой проверки, создайте новый класс и расширьте AbstractJavadocCheck , У него есть два абстрактных метода, которые вы должны реализовать:

Разница между грамматикой Java и комментариями Javadoc

Грамматика Java анализирует базу файлов Java на основе спецификаций языка Java. Итак, в нем есть однострочные комментарии и многострочные / блочные комментарии. Компилятор Java не знает о Javadoc, потому что это просто многострочный комментарий. Чтобы проанализировать многострочный комментарий как комментарий Javadoc, в checkstyle есть специальный Parser, основанный на грамматике Javadoc ANTLR. Таким образом, он должен обрабатывать блочные комментарии, которые начинаются с идентификатора Javadoc, и анализировать их в дереве абстрактного синтаксиса (AST).

Разница в том, что грамматика Java использует ANTLR v2, а грамматика Javadoc использует ANTLR v4. Из-за этого эти две грамматики и их деревья не совместимы. Java AST состоит из DetailAST объекты, в то время как Javadoc AST состоит из DetailNode объекты.

Основная грамматика Java пропускает любые пробелы и символы новой строки, поэтому в дереве абстрактного синтаксиса Java отсутствуют пробелы / узлы новой строки. В комментарии Javadoc каждый пробел имеет значение, и проверкам Javadoc нужны все эти пробелы и узлы новой строки для проверки формата и содержания комментария Javadoc. Из-за этого грамматика Javadoc включает в себя все пробелы, перевод строки в дерево разбора ( WS , НОВАЯ ЛИНИЯ ).

Инструмент для печати древовидной структуры Javadoc

Checkstyle может печатать абстрактное синтаксическое дерево для деревьев Java и Javadoc. Вам нужно запустить jar-файл checkstyle с аргументом -J , предоставляя java-файл

Например, вот файл MyClass.java:

/ ** * Мой <b> класс </ b>. * @see AbstractClass * / открытый класс MyClass {}

Команда:

java -jar checkstyle-X.XX-all.jar -J MyClass.java

Выход:

CLASS_DEF -> CLASS_DEF [5: 0] | --MODIFIERS -> MODIFIERS [5: 0] | | --BLOCK_COMMENT_BEGIN -> / * [1: 0] | | | --COMMENT_CONTENT -> * \ n * Мой <b> класс </ b>. \ N * @see AbstractClass \ n [1: 2] | | | `--JAVADOC -> JAVADOC [1: 3] | | | | --NEWLINE -> \ n [1: 3] | | | | --LEADING_ASTERISK -> * [2: 0] | | | | --TEXT -> My [2: 2] | | | | --HTML_ELEMENT -> HTML_ELEMENT [2: 6] | | | | `--HTML_TAG -> HTML_TAG [2: 6] | | | | | --HTML_ELEMENT_START -> HTML_ELEMENT_START [2: 6] | | | | | | --START -> <[2: 6] | | | | | | --HTML_TAG_NAME -> b [2: 7] | | | | | `--END ->> [2: 8] | | | | | --TEXT -> class [2: 9] | | | | `--HTML_ELEMENT_END -> HTML_ELEMENT_END [2:14] | | | | | --START -> <[2:14] | | | | | --SLASH -> / [2:15] | | | | | --HTML_TAG_NAME -> b [2:16] | | | | `--END ->> [2:17] | | | | --TEXT ->. [2:18] | | | | --NEWLINE -> \ n [2:19] | | | | --LEADING_ASTERISK -> * [3: 0] | | | | --WS -> [3: 2] | | | | --JAVADOC_TAG -> JAVADOC_TAG [3: 3] | | | | | --SEE_LITERAL -> @see [3: 3] | | | | | --WS -> [3: 7] | | | | | --REFERENCE -> ССЫЛКА [3: 8] | | | | | `--CLASS -> AbstractClass [3: 8] | | | | | --NEWLINE -> \ n [3:21] | | | | `--WS -> [4: 0] | | | `--EOF -> <EOF> [4: 1] | | `--BLOCK_COMMENT_END -> * / [4: 1] | `--LITERAL_PUBLIC -> public [5: 0] | --LITERAL_CLASS -> class [5: 7] | --IDENT -> MyClass [5:13]` --OBJBLOCK -> OBJBLOCK [5:21] | - -LCURLY -> {[5:21] `--RCURLY ->} [7: 0]

Как видите, очень маленький java-файл преобразуется в огромное абстрактное синтаксическое дерево, потому что это наиболее детальное дерево, включающее все компоненты java-файла: классы, методы, комментарии и т. Д.

В большинстве случаев при разработке Javadoc Check вам нужно только разобрать дерево точного комментария Javadoc. Для этого просто скопируйте комментарий Javadoc в отдельный файл и удалите / ** в начале и * / в конце. После этого запустите checkstyle с аргументом -j .

Файл MyJavadocComment.javadoc:

* Мой <b> класс </ b>. * @see AbstractClass

Команда:

java -jar checkstyle-X.XX-all.jar \ -j MyJavadocComment.javadoc

Выход:

JAVADOC -> JAVADOC [0: 0] | --LEADING_ASTERISK -> * [0: 0] | --TEXT -> My [0: 2] | --HTML_ELEMENT -> HTML_ELEMENT [0: 6] | `--HTML_TAG -> HTML_TAG [0: 6] | | --HTML_ELEMENT_START -> HTML_ELEMENT_START [0: 6] | | | --START -> <[0: 6] | | | --HTML_TAG_NAME -> b [0: 7] | | `--END ->> [0: 8] | | --TEXT -> class [0: 9] | `--HTML_ELEMENT_END -> HTML_ELEMENT_END [0:14] | | --START -> <[0:14] | | --SLASH -> / [0:15] | | --HTML_TAG_NAME -> b [0:16] | `--END ->> [0:17] | --TEXT ->. [0:18] | --NEWLINE -> \ n [0:19] | --LEADING_ASTERISK -> * [1: 0] | --WS -> [1: 2] | --JAVADOC_TAG -> JAVADOC_TAG [1 : 3] | | --SEE_LITERAL -> @see [1: 3] | | --WS -> [1: 7] | `--REFERENCE -> ССЫЛКА [1: 8] | `--CLASS -> AbstractClass [1: 8]` --EOF -> <EOF> [1:21]

Доступ к Java AST из проверки Javadoc

Как вы уже знаете, дерево синтаксического анализа Javadoc является результатом анализа блока комментариев. Есть способ получить исходный комментарий блока от Javadoc Check. Вам может понадобиться этот комментарий к блоку, чтобы проверить его положение или что-то еще в Java DetailAST дерево.

Например, чтобы написать JavadocCheck, который проверяет теги @param в комментарии Javadoc определения метода, вам также нужны имена всех параметров метода. Чтобы получить определение метода AST, вы должны получить доступ к Java DetailAST Дерево от Javadoc Проверьте. Для этого используйте getBlockCommentAst () метод, который возвращает DetailAST узел.

Пример:

класс MyCheck extends AbstractJavadocCheck {@Override public int [] getDefaultJavadocTokens () {return new int [] {JavadocTokenTypes.PARAMETER_NAME}; } @Override public void visitJavadocToken (DetailNode paramNameNode) {String javadocParamName = paramNameNode.getText (); DetailAST blockCommentAst = getBlockCommentAst (); if (BlockCommentPosition.isOnMethod (blockCommentAst)) {DetailAST methodDef = blockCommentAst.getParent (); DetailAST methodParam = findMethodParameter (methodDef); String methodParamName = methodParam.getText (); if (! javadocParamName.equals (methodParamName)) {log (methodParam, "params.dont.match"); }}}}

HTML-код в комментариях Javadoc

Checkstyle поддерживает теги HTML4 в комментариях Javadoc: все элементы HTML4 ,

HTML4 выбирается просто для того, чтобы иметь список элементов, конечный тег которых является необязательным (опускаемым) и список пустые элементы (также известен как пустые теги HTML , например Тег BR ).

Элементы HTML4, конечный тег которых является необязательным (опускается): <P>, <LI>, <TR>, <TD>, <TH>, <BODY>, <COLGROUP>, <DD>, <DT>, <HEAD> , <HTML>, <OPTION>, <TBODY>, <THEAD>, <TFOOT>.

Пустые элементы HTML4: <AREA>, <BASE>, <BASEFONT>, <BR>, <COL>, <FRAME>, <HR>, <IMG>, <INPUT>, <ISINDEX>, <LINK>, <META >, <PARAM>.

Чтобы Checkstyle поддерживал теги HTML5, конечный тег которых является необязательным (опускаемым), и пустые элементы HTML5, мы должны обновить Javadoc Parser, потому что каждый элемент, который ломается Жесткие правила HTML должны быть определены в грамматике Javadoc. В будущем нам следует обновить грамматику Javadoc, если эти списки расширятся (новые теги, новый стандарт HTML и т. Д.). (У нас уже есть вопрос об обновлении грамматики Javadoc до HTML5 )

Если Checkstyle встречает неизвестный тег (например, тег HTML5), он не завершается ошибкой и анализирует этот тег как HTML_TAG Тип токена Javadoc. Просто следуйте Жесткие правила HTML сделать Javadoc парсером Checkstyle сделать вложенный AST, хотя теги неизвестны.

<audio> <source src = "horse.ogg" type = "audio / ogg" /> </ audio> JAVADOC -> JAVADOC [0: 0] | --HTML_ELEMENT -> HTML_ELEMENT [0: 0] | `--HTML_TAG -> HTML_TAG [0: 0] | | --HTML_ELEMENT_START -> HTML_ELEMENT_START [0: 0] | | | --START -> <[0: 0] | | | --HTML_TAG_NAME -> аудио [0: 1] | | `--END ->> [0: 6] | | --HTML_ELEMENT -> HTML_ELEMENT [0: 7] | | `--SINGLETON_ELEMENT -> SINGLETON_ELEMENT [0: 7] | | `--EMPTY_TAG -> EMPTY_TAG [0: 7] | | | --START -> <[0: 7] | | | --HTML_TAG_NAME -> source [0: 8] | | | --WS -> [0:14] | | | --ATTRIBUTE -> ATTRIBUTE [0:15] | | | | --HTML_TAG_NAME -> src [0:15] | | | | --EQUALS -> = [0:18] | | | `--ATTR_VALUE ->" horse.ogg "[0:19] | | | --WS -> [0:31] | | | --ATTRIBUTE -> ATTRIBUTE [0:32] | | | | --HTML_TAG_NAME -> введите [0:32] | | | | --EQUALS -> = [0:36] | | | `--ATTR_VALUE ->" audio / ogg "[0:37] | | `--SLASH_END -> /> [0:49] | `--HTML_ELEMENT_END -> HTML_ELEMENT_END [0:51] | | --START -> <[0:51] | | --SLASH -> / [0:52] | | --HTML_TAG_NAME -> аудио [0:53] | `--END ->> [0:58]` --EOF -> <EOF> [0:59]

Вот что вы получите, если у неизвестного тега нет соответствующего конечного тега (например, тег HTML5 <audio>):
Входные данные:

Вывод: [ОШИБКА: 0] Комментарий Javadoc в столбце 1 содержит ошибку синтаксического анализа. Пропущенный HTML закрыть тег «аудио». Иногда это означает, что закрывающий тег пропущен для одного из предыдущих тегов.

Как вы видите, анализатор Javadoc печатает ошибку и не создает AST, если неизвестный HTML-тег не имеет конечного тега. Если это так, пожалуйста, создайте проблему с Checkstyle для обновления парсера.

Существуют также теги HTML, помеченные как «Не поддерживается в HTML5» ( Ссылка на элемент HTML ). Синтаксический анализатор Checkstyle Javadoc также может анализировать эти теги, если они написаны на Плотно HTML ,
Пример.
Входные данные:

<acronym title = "как можно скорее"> как можно скорее </ acronym>
Вывод: JAVADOC -> JAVADOC [0: 0] | --HTML_ELEMENT -> HTML_ELEMENT [0: 0] | `--HTML_TAG -> HTML_TAG [0: 0] | | --HTML_ELEMENT_START -> HTML_ELEMENT_START [0: 0] | | | --START -> <[0: 0] | | | --HTML_TAG_NAME -> аббревиатура [0: 1] | | | --WS -> [0: 8] | | | --ATTRIBUTE -> ATTRIBUTE [0: 9] | | | | --HTML_TAG_NAME -> title [0: 9] | | | | --EQUALS -> = [0:14] | | | `--ATTR_VALUE ->" как можно скорее "[0:15] | | `--END ->> [0:37] | | --TEXT -> ASAP [0:38] | `--HTML_ELEMENT_END -> HTML_ELEMENT_END [0:42] | | --START -> <[0:42] | | --SLASH -> / [0:43] | | --HTML_TAG_NAME -> аббревиатура [0:44] | `--END ->> [0:51]` --EOF -> <EOF> [0:52]

Больше примеров:

1) Незакрытый абзац HTML-тега. Как видно из дерева, содержимое тега абзаца не вложено в этот тег. Это связано с тем, что теги HTML не закрываются парным тегом </ p>, а Checkstyle требует Плотно HTML код для предсказуемого анализа комментариев Javadoc. 2) Вот правильная версия с открытыми и закрытыми тегами HTML. <p> Первая </ p> <p> Вторая </ p> JAVADOC -> JAVADOC [0: 0] | --HTML_ELEMENT -> HTML_ELEMENT [0: 0] | `--P_TAG_START -> P_TAG_START [0: 0] | | --START -> <[0: 0] | | --P_HTML_TAG_NAME -> p [0: 1] | `--END ->> [0: 2] | --TEXT -> First [0: 3] | --NEWLINE -> \ n [0: 9] | --HTML_ELEMENT -> HTML_ELEMENT [1: 0] | `--P_TAG_START -> P_TAG_START [1: 0] | | --START -> <[1: 0] | | --P_HTML_TAG_NAME -> p [1: 1] | `--END ->> [1: 2] | --TEXT -> Second [1: 3]` --EOF -> <EOF> [1:10] JAVADOC -> JAVADOC [0: 0] | - HTML_ELEMENT -> HTML_ELEMENT [0: 0] | `--PARAGRAPH -> PARAGRAPH [0: 0] | | --P_TAG_START -> P_TAG_START [0: 0] | | | --START -> <[0: 0] | | | --P_HTML_TAG_NAME -> p [0: 1] | | `--END ->> [0: 2] | | --TEXT -> Первый [0: 3] | `--P_TAG_END -> P_TAG_END [0:10] | | --START -> <[0:10] | | --SLASH -> / [0:11] | | --P_HTML_TAG_NAME -> p [0:12] | `--END ->> [0:13] | --NEWLINE -> \ n [0:14] | --HTML_ELEMENT -> HTML_ELEMENT [1: 0] | `--PARAGRAPH -> PARAGRAPH [1: 0] | | --P_TAG_START -> P_TAG_START [1: 0] | | | --START -> <[1: 0] | | | --P_HTML_TAG_NAME -> p [1: 1] | | `--END ->> [1: 2] | | --TEXT -> Second [1: 3] | `--P_TAG_END -> P_TAG_END [1:11] | | --START -> <[1:11] | | --SLASH -> / [1:12] | | --P_HTML_TAG_NAME -> p [1:13] | `--END ->> [1:14]` --EOF -> <EOF> [1:15]

Проверки также могут быть настроены для регистрации нарушений при обнаружении несжатых тегов HTML. Для этой цели можно использовать свойство violateExecutionOnNonTightHtml в проверках, которые его поддерживают. Пользовательская проверка должна расширять AbstractJavadocCheck для обеспечения доступности этой функциональности. Обратите внимание, что проверка, у которой для этого свойства установлено значение true, будет регистрировать нарушение только для первого найденного тега HTML. Чтобы проверка могла пропустить обработку javadoc с неэластичным HTML, метод acceptJavadocWithNonTightHtml в классе AbstractJavadocCheck может быть переопределен в проверке. В следующем примере показано, как использовать это свойство.

Входные данные:

/ ** * <body> * <p> Этот класс предназначен только для тестирования. </ p> * <p> Этот тег p не закрыт. Это не плотно. Приводит к нарушениям, если для проверки * <tt> violateExecutionOnNonTightHtml </ tt> установлено значение true. * <li> тугой тег li <p> ​​не тугой p тег, но только 1-й тэг li-in зарегистрирован в нарушении </ li> * </ body> * / public class Test {/ ** <p> < параграф. Это приведет к нарушению проверки <tt> JavadocParagraph </ tt> из-за избыточных тегов. </ p> </ p> * / private int field1; / ** <tr> Нулевое </ p> вложение, несмотря на то, что tr закрыто </ tr> * / private int field2; / ** * <p> этот абзац закрыт и будет вложен в дерево javadoc </ p> * <li> в этом списке есть <p> незамкнутый пункт, но все же список будет вложенным </ li> * / private int field3; / ** * <li> Завершить <p> вложение </ p> </ li> * / private int field4; }

Вывод с violateExecutionOnNonTightHtml установленным в false:

<! DOCTYPE module PUBLIC "- // Checkstyle // Конфигурация DTD Checkstyle 1.3 // EN" "https://checkstyle.org/dtds/configuration_1_3.dtd"> <module name = "Checker"> <имя модуля = "TreeWalker "> <module name =" JavadocParagraph "> <property name =" violateExecutionOnNonTightHtml "value =" false "/> </ module> </ module> </ module> Запуск аудита ... [ОШИБКА] Test.java:11: Избыточный тег <p>. [JavadocParagraph] Аудит завершен. Checkstyle заканчивается 1 ошибкой.

Вывод с violateExecutionOnNonTightHtml, установленным в true:

<! DOCTYPE module PUBLIC "- // Checkstyle // Конфигурация DTD Checkstyle 1.3 // EN" "https://checkstyle.org/dtds/configuration_1_3.dtd"> <module name = "Checker"> <имя модуля = "TreeWalker "> <module name =" JavadocParagraph "> <property name =" violateExecutionOnNonTightHtml "value =" true "/> </ module> </ module> </ module> Запуск аудита ... [ОШИБКА] Test.java:4: Обнаружен незамеченный HTML-тег: p [JavadocParagraph] [ERROR] Test.java:11: избыточный тег <p>. [JavadocParagraph] [ОШИБКА] Test.java:11: найден незакрытый тег HTML: p [JavadocParagraph] [ОШИБКА] Test.java:18: Обнаружен незакрытый тег HTML: tr [JavadocParagraph] [ОШИБКА] Test.java:23: Незакрытый HTML найден тег: p [JavadocParagraph] Аудит завершен. Checkstyle заканчивается 5 ошибками.

Checkstyle SDK GUI

Checkstyle GUI позволяет показывать дерево javadoc в файлах java. Для запуска в использовании

java -cp checkstyle-8.21-all.jar com.puppycrawl.tools.checkstyle.gui.Main

и выберите «JAVA WITH JAVADOC MODE» в выпадающем списке внизу фрейма.

Теперь вы можете видеть проанализированное дерево Javadoc как дочерний блок комментария.

Теперь вы можете видеть проанализированное дерево Javadoc как дочерний блок комментария

Обратите внимание, что могут быть открыты только файлы с расширением .java.

Для подробной информации вы можете увидеть Checkstyle GUI документация ,

Настройка типов токенов в проверках Javadoc

Проверки Java контролируются методом setTokens (), getDefaultTokens (), getAccessibleTokens (), getRequiredTokens (). Проверки JavaDoc используют ту же модель плюс дополнительные 4 метода для токенов Javadoc. Так как Java AST и Javadoc AST не связаны. Настоятельно рекомендуется, чтобы проверки Javadoc не использовали настройку Java-токенов и предполагалось, что они будут выполняться только на токенах Javadoc.

В классе AbstractJavadocCheck есть четыре метода для управления обработанным JavadocTokenTypes - один сеттер setJavadocTokens () , который используется для определения пользовательского набора (который отличается от набора по умолчанию) обработанных JavadocTokenTypes через файл конфигурации и три метода получения, которые должны быть переопределены: getDefaultJavadocTokens () , getAcceptableJavadocTokens () , getRequiredJavadocTokens () ,

  • setJavadocTokens () - метод, а затем определить фактический набор токенов для запуска.
  • getDefaultJavadocTokens () - возвращает набор JavadocTokenTypes, которые обрабатываются в visitToken () метод по умолчанию.
  • getRequiredJavadocTokens () - возвращает набор JavadocTokenTypes, на которые Check должен быть подписан для корректного выполнения. Если пользователь хочет указать пользовательский набор JavadocTokenTypes, тогда этот набор должен содержать все JavadocTokenTypes из RequiredJavadocTokens.
  • getAcceptableJavadocTokens () - возвращает набор, который содержит все JavadocTokenTypes, которые могут быть обработаны проверкой. И DefaultJavadocTokens, и RequiredJavadocTokens, и любой пользовательский набор JavadocTokenTypes являются подмножествами AcceptableJavadocTokens.

Примеры проверок Javadoc

Лучшие исходные знания о том, как писать Javadoc Checks, можно получить из существующие чеки ,

Поведение анализатора Javadoc для текущей версии HTML и новой версии HTML

В этом разделе показано, как синтаксический анализатор должен / будет вести себя при разборе текущей версии HTML и любой новой версии HTML. Текущая версия - HTML4, новая версия, которую необходимо поддерживать, - HTML5. GeneralToken - означает, что после разбора будет общий AstToken - HTML_TAG. SpecialToken - означает, что после разбора будет специальный AstToken - PARAGRAPH, ....

Теги с необязательным (опускаемым) конечным тегом:

Ввод Текущий стандарт (HTML4) Текущий стандарт с флагом hasUnclosedTag После обновления парсера для нового стандарта (HTML5) После обновления парсера для нового стандарта с флагом hasUnclosedTag <p> text </ p> Без ошибок, Вложенное дерево, SpecialToken Без ошибок, Вложенное дерево, SpecialToken, hasUnclosedTag = false Нет ошибок, Вложенное дерево, SpecialToken Нет ошибок, Вложенное дерево, SpecialToken, hasUnclosedTag = false <p> текст Нет ошибок, Не вложенное дерево, SpecialToken Нет ошибок, Не вложенное дерево, SpecialToken, hasUnclosedTag = true Нет ошибки, не вложенное дерево, SpecialToken Нет ошибок, не вложенное дерево, SpecialToken, hasUnclosedTag = true <rb> text </ rb>
Новый тег HTML5 с необязательным (пропускаемым) конечным тегом Без ошибок, Вложенное дерево, GeneralToken Нет ошибок, Вложенное дерево, GeneralToken, hasUnclosedTag = false Нет ошибок, Вложенное дерево, SpecialToken Без ошибок, Вложенное дерево, SpecialToken, hasUnclosedTag = false <rb> текст
Новый HTML5-тег с необязательным (пропускаемым) конечным тегом. Ошибка синтаксического анализа. Ошибка синтаксического анализа. Нет ошибок. Не вложенное дерево. SpecialToken. Нет ошибок. Не вложенное дерево. SpecialToken. HasUnclosedTag = true <qwerty> text </ qwerty>
Неизвестный тег HTML Нет ошибок, Вложенное дерево, GeneralToken Нет ошибок, Вложенное дерево, GeneralToken, hasUnclosedTag = false Нет ошибок, Вложенное дерево, GeneralToken Нет ошибок, Вложенное дерево, GeneralToken, hasUnclosedTag = false <qwerty> текст
Неизвестный тег HTML Ошибка разбора Ошибка разбора Ошибка разбора Ошибка разбора

Пустые теги:

Примечание: «Вложенные» / «Не вложенные» не применимы для этого типа тегов - все они выглядят как «Не вложенные». Flas "hasUnclosedTag" имеет значение "false" для всех случаев.

Ввод Текущий стандарт (HTML4) После обновления парсера для нового стандарта (HTML5) <br/> Без ошибок, SpecialToken Без ошибок, SpecialToken <br> Без ошибок, SpecialToken Без ошибок, SpecialToken <embed />
Новый тег HTML5 Без ошибок, GeneralToken Без ошибок, SpecialToken <embed>
Новый HTML5-тег Parse Error Нет ошибок, SpecialToken <basefont />
Поддерживается в HTML4. Не поддерживаемый тег в HTML5 Нет ошибок, SpecialToken Нет ошибок, SpecialToken <basefont>
Поддерживается в HTML4. Тег не поддерживается в HTML5 Нет ошибок, SpecialToken Нет ошибок, SpecialToken <qwerty />
Неизвестный тег HTML Нет ошибок, GeneralToken Нет ошибок, GeneralToken <qwerty>
Неизвестный тег HTML Ошибка разбора Ошибка разбора