writingjavadocchecks.html

<!DOCTYPE html>


<!--
 | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/writingjavadocchecks.xml.vm at 2025-04-02
 | Rendered using Apache Maven Fluido Skin 2.0.1
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
    <title>Writing Javadoc Checks – checkstyle</title>
    <link rel="stylesheet" href="./css/apache-maven-fluido-2.0.1.min.css" />
    <link rel="stylesheet" href="./css/site.css" />
    <link rel="stylesheet" href="./css/print.css" media="print" />
    <script src="./js/apache-maven-fluido-2.0.1.min.js"></script>
<script type="text/javascript" src="./js/checkstyle.js"></script>
        <script type="text/javascript" src="./js/anchors.js"></script>
        <script type="text/javascript" src="./js/google-analytics.js"></script>
        <script type="text/javascript" src="./js/copy-clipboard.js"></script>
        <link rel="icon" href="./images/favicon.png" type="image/x-icon" />
        <link rel="shortcut icon" href="./images/favicon.ico" type="image/ico" />
  </head>
  <body>
    <div class="container-fluid container-fluid-top">
      <header>
        <div id="banner">
          <div class="pull-left"><div id="bannerLeft"><h1><a href="./"><img class="class java.lang.Object" src="images/header-checkstyle-logo.png" alt="Checkstyle" /></a></h1></div></div>
          <div class="pull-right"><div id="bannerRight"><h1><img class="class java.lang.Object" src="images/header-right-ruller.png" alt="Checkstyle" /></h1></div></div>
          <div class="clear"><hr/></div>
        </div>

        <div id="breadcrumbs">
          <ul class="breadcrumb">
        <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2025-04-02</li>
          <li id="projectVersion" class="pull-right"><span class="divider">|</span>Version: 10.23.0</li>
        <li class="pull-right"><a>toTop</a></li>
          </ul>
        </div>
      </header>
      <div class="row-fluid">
        <header id="leftColumn" class="span2">
          <nav class="well sidebar-nav">
  <ul class="nav nav-list">
   <li class="nav-header">About</li>
    <li><a href="index.html">Checkstyle</a></li>
    <li><a href="releasenotes.html">Release Notes</a></li>
    <li><a href="consulting.html">Consulting</a></li>
    <li><a href="sponsoring.html">Sponsoring</a></li>
   <li class="nav-header">Documentation</li>
    <li><a href="config.html"><span class="icon-chevron-down"></span>Configuration</a>
     <ul class="nav nav-list">
      <li><a href="property_types.html">Property Types</a></li>
      <li><a href="config_system_properties.html">System Properties</a></li>
     </ul></li>
    <li><a href="running.html"><span class="icon-chevron-down"></span>Running</a>
     <ul class="nav nav-list">
      <li><a href="anttask.html">Ant Task</a></li>
      <li><a href="cmdline.html">Command Line</a></li>
     </ul></li>
    <li><a href="checks.html"><span class="icon-chevron-down"></span>Checks</a>
     <ul class="nav nav-list">
      <li><a href="checks/annotation/index.html"><span class="icon-chevron-right"></span>Annotations</a></li>
      <li><a href="checks/blocks/index.html"><span class="icon-chevron-right"></span>Block Checks</a></li>
      <li><a href="checks/design/index.html"><span class="icon-chevron-right"></span>Class Design</a></li>
      <li><a href="checks/coding/index.html"><span class="icon-chevron-right"></span>Coding</a></li>
      <li><a href="checks/header/index.html"><span class="icon-chevron-right"></span>Headers</a></li>
      <li><a href="checks/imports/index.html"><span class="icon-chevron-right"></span>Imports</a></li>
      <li><a href="checks/javadoc/index.html"><span class="icon-chevron-right"></span>Javadoc Comments</a></li>
      <li><a href="checks/metrics/index.html"><span class="icon-chevron-right"></span>Metrics</a></li>
      <li><a href="checks/misc/index.html"><span class="icon-chevron-right"></span>Miscellaneous</a></li>
      <li><a href="checks/modifier/index.html"><span class="icon-chevron-right"></span>Modifiers</a></li>
      <li><a href="checks/naming/index.html"><span class="icon-chevron-right"></span>Naming Conventions</a></li>
      <li><a href="checks/regexp/index.html"><span class="icon-chevron-right"></span>Regexp</a></li>
      <li><a href="checks/sizes/index.html"><span class="icon-chevron-right"></span>Size Violations</a></li>
      <li><a href="checks/whitespace/index.html"><span class="icon-chevron-right"></span>Whitespace</a></li>
     </ul></li>
    <li><a href="filters/index.html"><span class="icon-chevron-right"></span>Filters</a></li>
    <li><a href="filefilters/index.html"><span class="icon-chevron-right"></span>File Filters</a></li>
    <li><a href="style_configs.html"><span class="icon-chevron-down"></span>Style Configurations</a>
     <ul class="nav nav-list">
      <li><a href="google_style.html">Google&apos;s Style</a></li>
      <li><a href="sun_style.html">Sun&apos;s Style</a></li>
     </ul></li>
   <li class="nav-header">Developers</li>
    <li><a href="extending.html"><span class="icon-chevron-down"></span>Extending Checkstyle</a>
     <ul class="nav nav-list">
      <li><a href="writingchecks.html">Writing Checks</a></li>
      <li class="active"><a>Writing Javadoc Checks</a></li>
      <li><a href="writingfilters.html">Writing Filters</a></li>
      <li><a href="writingfilefilters.html">Writing File Filters</a></li>
      <li><a href="writinglisteners.html">Writing Listeners</a></li>
     </ul></li>
    <li><a href="contributing.html">Contributing</a></li>
    <li><a href="beginning_development.html"><span class="icon-chevron-down"></span>Beginning Development</a>
     <ul class="nav nav-list">
      <li><a href="eclipse.html">Eclipse IDE</a></li>
      <li><a href="netbeans.html">NetBeans IDE</a></li>
      <li><a href="idea.html">IntelliJ IDE</a></li>
     </ul></li>
    <li><a href="apidocs/index.html">Javadoc</a></li>
   <li class="nav-header">Project Documentation</li>
    <li><a href="project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
    <li><a href="project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
  </ul>
          </nav>
          <div class="well sidebar-nav">
            <div id="poweredBy">
              <div class="clear"></div>
              <div class="clear"></div>
<a href="https://github.com/checkstyle/checkstyle" class="builtBy"><img class="builtBy" src="images/github_logo_social_coding_outlined.png" alt="GitHub" /></a>
<a href="https://twitter.com/checkstyle_java/" class="builtBy"><img class="builtBy" src="images/twitter_button.png" alt="Twitter" /></a>
<a href="https://stackoverflow.com/questions/tagged/checkstyle" class="builtBy"><img class="builtBy" src="images/stackoverflow.jpeg" alt="Stackoverflow" /></a>
<a href="https://groups.google.com/forum/#!forum/checkstyle" class="builtBy"><img class="builtBy" src="images/groups.png" alt="GoogleGroups" /></a>
<a href="https://www.ej-technologies.com/products/jprofiler/overview.html" class="builtBy"><img class="builtBy" src="https://www.ej-technologies.com/images/product_banners/jprofiler_medium.png" alt="JProfiler" /></a>
            </div>
          </div>
        </header>
        <main id="bodyColumn" class="span10">


    <section><a id="Content"></a>
<h1>Content</h1>
      
        
<ul>
<li><a href="#Content">Content</a></li>
<li><a href="#What_is_Javadoc_comment">What is Javadoc comment</a></li>
<li><a href="#Limitations">Limitations</a></li>
<li><a href="#Tight-HTML_rules">Tight-HTML rules</a></li>
<li><a href="#How_to_create_Javadoc_Check">How to create Javadoc Check</a></li>
<li><a href="#Difference_between_Java_Grammar_and_Javadoc_comments_Grammar">Difference between Java Grammar and Javadoc comments Grammar</a></li>
<li><a href="#Tool_to_print_Javadoc_tree_structure">Tool to print Javadoc tree structure</a></li>
<li><a href="#Access_Java_AST_from_Javadoc_Check">Access Java AST from Javadoc Check</a></li>
<li><a href="#HTML_Code_In_Javadoc_Comments">HTML Code In Javadoc Comments</a></li>
<li><a href="#Checkstyle_SDK_GUI">Checkstyle SDK GUI</a></li>
<li><a href="#Customize_token_types_in_Javadoc_Checks">Customize token types in Javadoc Checks</a></li>
<li><a href="#Integrating_new_Javadoc_Check">Integrating new Javadoc Check</a></li>
<li><a href="#Declare_check.27s_external_resource_locations">Declare check's external resource locations</a></li>
<li><a href="#Examples_of_Javadoc_Checks">Examples of Javadoc Checks</a></li>
<li><a href="#Javadoc_parser_behavior_for_current_HTML_version_and_new_HTML_version">Javadoc parser behavior for current HTML version and new HTML version</a></li></ul>
    </section>

    <section><a id="What_is_Javadoc_comment"></a>
<h1>What is Javadoc comment</h1>
      
<p>
      Javadoc comment is a multiline comment <code>/*  */</code> that starts with the <b>*</b>
      character and placed above the class definition, interface definition, enum definition,
      method definition or field definition.
      If an annotation precedes any of the definitions listed above, then the javadoc comment
      should be placed before the annotation.
      If several multiline comments with javadoc identifiers are placed sequentially, only
      the one closest to the definition, right above it, with the javadoc identifier will be used.
      </p>
      
<p>
        Javadoc comments should contain: a short summary (the first sentence), an optional
        documentation section, an optional tag section. The first sentence has a special meaning
        and should be clear, punchy, short, and is ended by a period symbol.
        Immediately after the first sentence, the main description could begin,
        which may be followed by the tag section. The tag section starts with the first block tag,
        which is defined by the first <code>@</code> character that begins a line
        (ignoring leading asterisks, white space, and leading separator <code>/**</code>).
      </p>
      
<p>For example, here is java file:</p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
/**
 * My &lt;b&gt;class&lt;/b&gt;.
 *
 * @see Annotation
 */
public class MyClass {

  /** Not a javadoc (ignored). */

  /**
   * Doubles the value.
   * The long and detailed explanation what the method does.
   *
   * @param value for doubling.
   * @return double value.
   */

  /*
   Multiline comment (ignored).
  */
  @Annotation
  /** Extra javadoc (ignored). */
  // Single line comment (ignored).
  public int method(int value) {
    /** Inner javadoc (ignored). */
    return value * 2;
  }
}
      </code></pre></div>
      
<p>Javadoc content for the MyClass will be:</p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
    My &lt;b&gt;class&lt;/b&gt;.

    @see Annotation
      </code></pre></div>
      
<p>Javadoc content for the MyClass.method will be:</p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
    Doubles the value.
    The long and detailed explanation what the method does.

    @param value for doubling.
    @return double value.
      </code></pre></div>
      
<p>
      Attention that java comment starts with <code>/*</code>, following with Identifier of
      comment type. Javadoc Identifier is <code>*</code>. All symbols after Javadoc
      Identifier till <code>*/</code> are part of javadoc comment.
      </p>
      
<p>Please note that javadoc-like (multiline comment with javadoc identifier) comment inside
      a method is not a javadoc comment and skipped by Sun/Oracle javadoc tool and by our javadoc
      comment matcher, but such comment will be in AST.
      </p>
      
<p>
        You can find different types of documentation generation tools similar to javadoc on the
        Internet. Such tools rely on specific Identifier: &quot;!&quot;, &quot;#&quot;, &quot;$&quot;.
        Comments look like <code>&quot;/*! some comment */&quot;</code> , <code>&quot;/*# some comment */&quot;</code> ,
        <code>&quot;/*$ some comment */&quot;</code>. Such multiline comments are not a javadoc.
      </p>
    </section>

    <section><a id="Limitations"></a>
<h1>Limitations</h1>
      
<p>
      Since Oracle itself does not provide a comprehensive language specification for Javadocs,
      we have interpreted the existing behavior of the Javadoc tool and accepted standards
      to form our Javadoc grammar and Abstract Syntax Tree (AST). For this reason, we must
      impose the following limitations on Javadoc parsing and checks.
      </p>
      
<p>
      The comment should be written in <a href="#Tight-HTML_rules">Tight-HTML</a>
          to build ASTs that most Checks expect.
      </p>
      
<p>
        For more details about parsing of HTML into AST read
        <a href="#HTML_Code_In_Javadoc_Comments">HTML Code In Javadoc Comments</a>
        and <a href="#Javadoc_parser_behavior_for_current_HTML_version_and_new_HTML_version">
          Javadoc parser behavior
        </a>  section.
      </p>
    </section>

    <section><a id="Tight-HTML_rules"></a>
<h1>Tight-HTML rules</h1>
      
<p>
        Every HTML tag should have matching end HTML tag or it is a
        <a href="https://www.w3.org/TR/html/syntax.html#void-elements" class="externalLink">void element</a>.
      </p>
      
<p>
        The only exceptions are HTML 4 tags whose end tag is optional (omittable) by
        HTML specification (example is
        <a href="https://www.w3.org/TR/html5/tabular-data.html#the-tr-element" class="externalLink">TR</a>), so,
        Checkstyle won't show an error about missing end tags, however,
        it leads to broken Tight-HTML structure and as a result leads to non-nested content
        of the HTML tags in the Abstract Syntax Tree of the Javadoc comment.
        <br />
        In other words, if HTML tags are not closed in Javadoc, our parser cannot determine the
        content of these tags, so structure of the parse tree will not be nested like it is while
        using <a href="#Tight-HTML_rules">Tight-HTML</a>.
      </p>
      
<p>
      Other rules:
      </p>
      
<ul>
        
<li>Document Structure elements (DOCTYPE, &lt;html&gt;, &lt;body&gt;, etc) are
            not mandatory.</li>
        
<li>Elements must always be closed, except HTML4 elements whose end tag is optional
          (omittable) and HTML4
          <a href="https://www.w3.org/TR/html/syntax.html#void-elements" class="externalLink">void elements</a>.
          See <a href="#HTML_Code_In_Javadoc_Comments">HTML Code In Javadoc Comments</a>
          section
        </li>
        
<li>HTML elements can be either in lowercase or in uppercase</li>
        
<li>Attribute names can be either in lowercase or in uppercase</li>
        
<li>Attribute values can be either quoted or not be quoted</li>
      </ul>
    </section>

    <section><a id="How_to_create_Javadoc_Check"></a>
<h1>How to create Javadoc Check</h1>
      
<p>
        Writing Javadoc Checks is similar to writing Java Checks, however you should extend
        AbstractJavadocCheck&lt;link&gt; and use JavadoctokenTypes&lt;link&gt;.
      </p>
      
<p>
      To start implementing new Check create a new class and extend <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html">
          AbstractJavadocCheck</a>.
      It has two abstract methods you should implement:
      </p>
      
<ul>
        
<li>
          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getDefaultJavadocTokens--">
              getDefaultJavadocTokens()</a> - return int array of
          javadoc token types your Check is going to process.
          The array should contain int constants from
          <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html">
          JavadocTokenTypes</a> class. (There is also
          <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html">
              TokenTypes</a> class in Checkstyle. Make sure you use
          <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html">
              JavadocTokenTypes</a> class in your Check, because the
          <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html">
              TokenTypes</a> is used to describe standard Java
          <a href="apidocs/com/puppycrawl/tools/checkstyle/api/DetailAST.html">
              DetailAST</a> token type.)
        </li>
        
<li>
          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#visitJavadocToken-com.puppycrawl.tools.checkstyle.api.DetailNode-">
          visitJavadocToken(DetailNode)</a> - it's a place you should put tree nodes processing.
          The argument is Javadoc tree node of type you described before in
          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getDefaultJavadocTokens--">
              getDefaultJavadocTokens()</a> method.
        </li>
      </ul>
    </section>

    <section><a id="Difference_between_Java_Grammar_and_Javadoc_comments_Grammar"></a>
<h1>Difference between Java Grammar and Javadoc comments Grammar</h1>
      
<p>
        Our Java parser parses all multiline comments (C-style comments and Javadoc comments)
        as block comments, whether they are Javadocs or not. Our Javadoc parser then transforms
        these block comment ASTs into our Javadoc AST.
      </p>
      
<p>
        The difference is that Java grammar uses ANTLR v2, while Javadoc grammar uses ANTLR v4.
        Because of that, these two grammars and their trees are not compatible.
        Java AST consists of
        <a href="apidocs/com/puppycrawl/tools/checkstyle/api/DetailAST.html">DetailAST</a>
        objects, while Javadoc AST consists of
        <a href="apidocs/com/puppycrawl/tools/checkstyle/api/DetailNode.html">DetailNode</a>
        objects.
      </p>
      
<p>
        Our Java grammar ignores whitespace in most cases, since Java itself does not care about
        whitespace; however, whitespace is critical in Javadocs. For this reason, our Javadoc AST
        retains most whitespace that is present in the Javadoc.
        (<a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#WS">WS</a>,
        <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#NEWLINE">
            NEWLINE</a>).
      </p>
    </section>

    <section><a id="Tool_to_print_Javadoc_tree_structure"></a>
<h1>Tool to print Javadoc tree structure</h1>
      
<p>
      Checkstyle can print a combined Java and Javadoc Abstract Syntax Tree. You need to run the
      checkstyle jar file with the <b>-J</b> argument, providing a java file.
      </p>
      
<p>For example, here is MyClass.java file:</p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
/**
 * My &lt;b&gt;class&lt;/b&gt;.
 * @see AbstractClass
 */
public class MyClass {

}
      </code></pre></div>
      
<p>Command:</p>
      
<div class="wrap-content">
        
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
          java -jar checkstyle-X.XX-all.jar -J MyClass.java
        </code></pre></div>
      </div>
      
<p>Output:</p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
CLASS_DEF -&gt; CLASS_DEF [5:0]
|--MODIFIERS -&gt; MODIFIERS [5:0]
|   |--BLOCK_COMMENT_BEGIN -&gt; /* [1:0]
|   |   |--COMMENT_CONTENT -&gt; *\n * My &lt;b&gt;class&lt;/b&gt;.\n * @see AbstractClass\n  [1:2]
|   |   |   `--JAVADOC -&gt; JAVADOC [1:3]
|   |   |       |--NEWLINE -&gt; \n [1:3]
|   |   |       |--LEADING_ASTERISK -&gt;  * [2:0]
|   |   |       |--TEXT -&gt;  My  [2:2]
|   |   |       |--HTML_ELEMENT -&gt; HTML_ELEMENT [2:6]
|   |   |       |   `--HTML_TAG -&gt; HTML_TAG [2:6]
|   |   |       |       |--HTML_ELEMENT_START -&gt; HTML_ELEMENT_START [2:6]
|   |   |       |       |   |--START -&gt; &lt; [2:6]
|   |   |       |       |   |--HTML_TAG_NAME -&gt; b [2:7]
|   |   |       |       |   `--END -&gt; &gt; [2:8]
|   |   |       |       |--TEXT -&gt; class [2:9]
|   |   |       |       `--HTML_ELEMENT_END -&gt; HTML_ELEMENT_END [2:14]
|   |   |       |           |--START -&gt; &lt; [2:14]
|   |   |       |           |--SLASH -&gt; / [2:15]
|   |   |       |           |--HTML_TAG_NAME -&gt; b [2:16]
|   |   |       |           `--END -&gt; &gt; [2:17]
|   |   |       |--TEXT -&gt; . [2:18]
|   |   |       |--NEWLINE -&gt; \n [2:19]
|   |   |       |--LEADING_ASTERISK -&gt;  * [3:0]
|   |   |       |--WS -&gt;   [3:2]
|   |   |       |--JAVADOC_TAG -&gt; JAVADOC_TAG [3:3]
|   |   |       |   |--SEE_LITERAL -&gt; @see [3:3]
|   |   |       |   |--WS -&gt;   [3:7]
|   |   |       |   |--REFERENCE -&gt; REFERENCE [3:8]
|   |   |       |   |   `--CLASS -&gt; AbstractClass [3:8]
|   |   |       |   |--NEWLINE -&gt; \n [3:21]
|   |   |       |   `--WS -&gt;   [4:0]
|   |   |       `--EOF -&gt; &lt;EOF&gt; [4:1]
|   |   `--BLOCK_COMMENT_END -&gt; */ [4:1]
|   `--LITERAL_PUBLIC -&gt; public [5:0]
|--LITERAL_CLASS -&gt; class [5:7]
|--IDENT -&gt; MyClass [5:13]
`--OBJBLOCK -&gt; OBJBLOCK [5:21]
    |--LCURLY -&gt; { [5:21]
    `--RCURLY -&gt; } [7:0]
      </code></pre></div>
      
<p>
        In most cases while developing Javadoc Checks, you need to only parse the tree of the exact
        Javadoc comment. To do that just copy Javadoc comment to a separate file and remove
        <b>/**</b> at the beginning and <b>*/</b> at the end. After that, run checkstyle with
        <b>-j</b> argument.
      </p>
      
<p>MyJavadocComment.javadoc file:</p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
 * My &lt;b&gt;class&lt;/b&gt;.
 * @see AbstractClass
      </code></pre></div>
      
<p>Command:</p>
      
<div class="wrap-content">
        
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
          java -jar checkstyle-X.XX-all.jar \
          &#xa0;&#xa0;&#xa0;&#xa0;-j MyJavadocComment.javadoc
        </code></pre></div>
      </div>
      
<p>Output:</p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
JAVADOC -&gt; JAVADOC [0:0]
|--LEADING_ASTERISK -&gt;  * [0:0]
|--TEXT -&gt;  My  [0:2]
|--HTML_ELEMENT -&gt; HTML_ELEMENT [0:6]
|   `--HTML_TAG -&gt; HTML_TAG [0:6]
|       |--HTML_ELEMENT_START -&gt; HTML_ELEMENT_START [0:6]
|       |   |--START -&gt; &lt; [0:6]
|       |   |--HTML_TAG_NAME -&gt; b [0:7]
|       |   `--END -&gt; &gt; [0:8]
|       |--TEXT -&gt; class [0:9]
|       `--HTML_ELEMENT_END -&gt; HTML_ELEMENT_END [0:14]
|           |--START -&gt; &lt; [0:14]
|           |--SLASH -&gt; / [0:15]
|           |--HTML_TAG_NAME -&gt; b [0:16]
|           `--END -&gt; &gt; [0:17]
|--TEXT -&gt; . [0:18]
|--NEWLINE -&gt; \n [0:19]
|--LEADING_ASTERISK -&gt;  * [1:0]
|--WS -&gt;   [1:2]
|--JAVADOC_TAG -&gt; JAVADOC_TAG [1:3]
|   |--SEE_LITERAL -&gt; @see [1:3]
|   |--WS -&gt;   [1:7]
|   `--REFERENCE -&gt; REFERENCE [1:8]
|       `--CLASS -&gt; AbstractClass [1:8]
`--EOF -&gt; &lt;EOF&gt; [1:21]
      </code></pre></div>
    </section>

    <section><a id="Access_Java_AST_from_Javadoc_Check"></a>
<h1>Access Java AST from Javadoc Check</h1>
      
<p>
        As you already know the Javadoc AST is a result of parsing a block comment.
        There is a method to get the original block comment from a Javadoc Check.
        You may need this block comment to check its position in the
        <a href="apidocs/com/puppycrawl/tools/checkstyle/api/DetailAST.html">DetailAST</a> tree.
      </p>
      
<p>
        For example, to write a JavadocCheck that verifies @param tags in the Javadoc comment of
        a method definition, you also need all of the method's parameter names. To get a method
        definition AST you should access the
        <a href="apidocs/com/puppycrawl/tools/checkstyle/api/DetailAST.html">DetailAST</a> tree
        from a javadoc Check. For this purpose use the
        <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getBlockCommentAst--">
            getBlockCommentAst()</a>
        method that returns a
        <a href="apidocs/com/puppycrawl/tools/checkstyle/api/DetailAST.html">DetailAST</a> node.
      </p>
      
<p>
        Example:
      </p>
      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
class 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, &quot;params.dont.match&quot;);
            }

        }
    }
}
      </code></pre></div>
    </section>

    <section><a id="HTML_Code_In_Javadoc_Comments"></a>
<h1>HTML Code In Javadoc Comments</h1>
      
<p>
        Checkstyle supports HTML4 tags in Javadoc comments:
        <a href="https://www.w3.org/TR/html4/index/elements.html" class="externalLink">
          all HTML4 elements
        </a>.
      </p>
      
<p>
        HTML4 is designed to have a list of elements whose end tag is optional(omittable) and a
        list of <a href="https://www.w3.org/TR/html/syntax.html#void-elements" class="externalLink">void elements</a>
        (also known as <a href="https://www.w3schools.com/html/html_elements.asp" class="externalLink">empty html
        tags</a>, for example <a href="https://www.w3.org/TR/html4/struct/text.html#edef-BR" class="externalLink">BR
        tag</a>).
      </p>
      
<p>
        HTML4 elements whose end tag is optional (omittable): &lt;P&gt;, &lt;LI&gt;, &lt;TR&gt;,
        &lt;TD&gt;, &lt;TH&gt;, &lt;BODY&gt;, &lt;COLGROUP&gt;, &lt;DD&gt;, &lt;DT&gt;,
        &lt;HEAD&gt;, &lt;HTML&gt;, &lt;OPTION&gt;, &lt;TBODY&gt;, &lt;THEAD&gt;, &lt;TFOOT&gt;.
      </p>
      
<p>
        Void HTML4 elements: &lt;AREA&gt;, &lt;BASE&gt;, &lt;BASEFONT&gt;, &lt;BR&gt;, &lt;COL&gt;,
        &lt;FRAME&gt;, &lt;HR&gt;, &lt;IMG&gt;, &lt;INPUT&gt;, &lt;ISINDEX&gt;, &lt;LINK&gt;,
        &lt;META&gt;, &lt;PARAM&gt;.
      </p>

      
<p>
        Checkstyle does not support HTML5 tags with optional end tags. See
        <a href="https://github.com/checkstyle/checkstyle/issues/3332" class="externalLink">issue</a> for details.
      </p>

      
<p>
        If the parser consumes an unknown tag (for example HTML5 tag)
        it doesn't fail, but parses this tag as a
        <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#HTML_TAG">
            HTML_TAG</a>
          Javadoc token type.
        Always follow <a href="#Tight-HTML_rules">Tight-HTML rules</a> to make the
        Checkstyle javadoc parser create nested ASTs, even though tags are unknown.

        
<div class="wrapper"></p>
<pre class="prettyprint"><code class="language-xml">
&lt;audio&gt;&lt;source src=&quot;horse.ogg&quot; type=&quot;audio/ogg&quot;/&gt;&lt;/audio&gt;
        </code></pre></div>

        
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
JAVADOC -&gt; JAVADOC [0:0]
|--HTML_ELEMENT -&gt; HTML_ELEMENT [0:0]
|   `--HTML_TAG -&gt; HTML_TAG [0:0]
|       |--HTML_ELEMENT_START -&gt; HTML_ELEMENT_START [0:0]
|       |   |--START -&gt; &lt; [0:0]
|       |   |--HTML_TAG_NAME -&gt; audio [0:1]
|       |   `--END -&gt; &gt; [0:6]
|       |--HTML_ELEMENT -&gt; HTML_ELEMENT [0:7]
|       |   `--SINGLETON_ELEMENT -&gt; SINGLETON_ELEMENT [0:7]
|       |       `--EMPTY_TAG -&gt; EMPTY_TAG [0:7]
|       |           |--START -&gt; &lt; [0:7]
|       |           |--HTML_TAG_NAME -&gt; source [0:8]
|       |           |--WS -&gt;   [0:14]
|       |           |--ATTRIBUTE -&gt; ATTRIBUTE [0:15]
|       |           |   |--HTML_TAG_NAME -&gt; src [0:15]
|       |           |   |--EQUALS -&gt; = [0:18]
|       |           |   `--ATTR_VALUE -&gt; &quot;horse.ogg&quot; [0:19]
|       |           |--WS -&gt;   [0:31]
|       |           |--ATTRIBUTE -&gt; ATTRIBUTE [0:32]
|       |           |   |--HTML_TAG_NAME -&gt; type [0:32]
|       |           |   |--EQUALS -&gt; = [0:36]
|       |           |   `--ATTR_VALUE -&gt; &quot;audio/ogg&quot; [0:37]
|       |           `--SLASH_END -&gt; /&gt; [0:49]
|       `--HTML_ELEMENT_END -&gt; HTML_ELEMENT_END [0:51]
|           |--START -&gt; &lt; [0:51]
|           |--SLASH -&gt; / [0:52]
|           |--HTML_TAG_NAME -&gt; audio [0:53]
|           `--END -&gt; &gt; [0:58]
`--EOF -&gt; &lt;EOF&gt; [0:59]
        </code></pre></div>
      

<p>
        This is an example of parsing an unknown tag that doesn't have a matching end tag (for
        example, HTML5 tag &lt;audio&gt;): <br />
        Input:
        
<div class="wrapper"></p>
<pre class="prettyprint"><code class="language-xml">
        &lt;audio&gt;test
        </code></pre></div>
        Output:
      
      
<div class="wrap-content">
        
<div class="wrapper">
<pre class="prettyprint"><code class="language-text">
          [ERROR:0] Javadoc comment at column 1 has parse error. Missed HTML close tag 'audio'.
          Sometimes it means that close tag missed for one of previous tags.
        </code></pre></div>
      </div>
      
<p>
        As you see, the Javadoc parser prints an error and doesn't build the AST if an unknown
        HTML tag doesn't have a matching end tag. If that's the case, please create an issue for
        Checkstyle to consider adding support for this tag.
      </p>

      
<p>
        There are also HTML tags that are marked as &quot;Not supported in HTML5&quot;
        (<a href="https://www.w3schools.com/tags/default.asp" class="externalLink">HTML Element Reference</a>).
        Checkstyle Javadoc parser can parse those tags too if they are written in
        <a href="#Tight-HTML_rules">Tight-HTML</a>.
        <br />
        Example:
        <br />
        Input:
        
<div class="wrapper"></p>
<pre class="prettyprint"><code class="language-xml">
&lt;acronym title=&quot;as soon as possible&quot;&gt;ASAP&lt;/acronym&gt;

        </code></pre></div>
        <br />
        Output:
        
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
JAVADOC -&gt; JAVADOC [0:0]
|--HTML_ELEMENT -&gt; HTML_ELEMENT [0:0]
|   `--HTML_TAG -&gt; HTML_TAG [0:0]
|       |--HTML_ELEMENT_START -&gt; HTML_ELEMENT_START [0:0]
|       |   |--START -&gt; &lt; [0:0]
|       |   |--HTML_TAG_NAME -&gt; acronym [0:1]
|       |   |--WS -&gt;   [0:8]
|       |   |--ATTRIBUTE -&gt; ATTRIBUTE [0:9]
|       |   |   |--HTML_TAG_NAME -&gt; title [0:9]
|       |   |   |--EQUALS -&gt; = [0:14]
|       |   |   `--ATTR_VALUE -&gt; &quot;as soon as possible&quot; [0:15]
|       |   `--END -&gt; &gt; [0:37]
|       |--TEXT -&gt; ASAP [0:38]
|       `--HTML_ELEMENT_END -&gt; HTML_ELEMENT_END [0:42]
|           |--START -&gt; &lt; [0:42]
|           |--SLASH -&gt; / [0:43]
|           |--HTML_TAG_NAME -&gt; acronym [0:44]
|           `--END -&gt; &gt; [0:51]
`--EOF -&gt; &lt;EOF&gt; [0:52]

        </code></pre></div>
      

<p>More examples:</p>

      
<div class="wrapper">
        
<table class="table table-striped" style="table-layout: fixed;">
          
<tr class="a">
            
<td>
              1) Unclosed paragraph HTML tag. As you see in the tree, the content of the paragraph
              tag is not nested within this tag.
              That is because HTML tags are not closed by pair tags &lt;/p&gt;, and Checkstyle
              requires <a href="#Tight-HTML_rules">Tight-HTML</a> code to predictably parse
              Javadoc comments.
            </td>
            
<td>
              2) Here is a correct example with open and closed HTML tags.
            </td>
          </tr>

          
<tr class="b">
            
<td>
              
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
&lt;p&gt; First
&lt;p&gt; Second

              </code></pre></div>
            </td>
            
<td>
              
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
&lt;p&gt; First &lt;/p&gt;
&lt;p&gt; Second &lt;/p&gt;

              </code></pre></div>
            </td>
          </tr>

          
<tr class="a">
            
<td>
              
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
JAVADOC -&gt; JAVADOC [0:0]
|--HTML_ELEMENT -&gt; HTML_ELEMENT [0:0]
|   `--P_TAG_START -&gt; P_TAG_START [0:0]
|       |--START -&gt; &lt; [0:0]
|       |--P_HTML_TAG_NAME -&gt; p [0:1]
|       `--END -&gt; &gt; [0:2]
|--TEXT -&gt;  First [0:3]
|--NEWLINE -&gt; \n [0:9]
|--HTML_ELEMENT -&gt; HTML_ELEMENT [1:0]
|   `--P_TAG_START -&gt; P_TAG_START [1:0]
|       |--START -&gt; &lt; [1:0]
|       |--P_HTML_TAG_NAME -&gt; p [1:1]
|       `--END -&gt; &gt; [1:2]
|--TEXT -&gt;  Second [1:3]
`--EOF -&gt; &lt;EOF&gt; [1:10]

              </code></pre></div>
            </td>
            
<td>
              
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
JAVADOC -&gt; JAVADOC [0:0]
|--HTML_ELEMENT -&gt; HTML_ELEMENT [0:0]
|   `--PARAGRAPH -&gt; PARAGRAPH [0:0]
|       |--P_TAG_START -&gt; P_TAG_START [0:0]
|       |   |--START -&gt; &lt; [0:0]
|       |   |--P_HTML_TAG_NAME -&gt; p [0:1]
|       |   `--END -&gt; &gt; [0:2]
|       |--TEXT -&gt;  First  [0:3]
|       `--P_TAG_END -&gt; P_TAG_END [0:10]
|           |--START -&gt; &lt; [0:10]
|           |--SLASH -&gt; / [0:11]
|           |--P_HTML_TAG_NAME -&gt; p [0:12]
|           `--END -&gt; &gt; [0:13]
|--NEWLINE -&gt; \n [0:14]
|--HTML_ELEMENT -&gt; HTML_ELEMENT [1:0]
|   `--PARAGRAPH -&gt; PARAGRAPH [1:0]
|       |--P_TAG_START -&gt; P_TAG_START [1:0]
|       |   |--START -&gt; &lt; [1:0]
|       |   |--P_HTML_TAG_NAME -&gt; p [1:1]
|       |   `--END -&gt; &gt; [1:2]
|       |--TEXT -&gt;  Second  [1:3]
|       `--P_TAG_END -&gt; P_TAG_END [1:11]
|           |--START -&gt; &lt; [1:11]
|           |--SLASH -&gt; / [1:12]
|           |--P_HTML_TAG_NAME -&gt; p [1:13]
|           `--END -&gt; &gt; [1:14]
`--EOF -&gt; &lt;EOF&gt; [1:15]

              </code></pre></div>
            </td>
          </tr>
        </table>
      </div>

      
<p>
        Checks can also be configured to log violations upon encountering non-tight HTML tags.
        The <code>violateExecutionOnNonTightHtml</code> property can be used for this purpose in the
        checks that support it. A custom check needs to extend <code>AbstractJavadocCheck</code> to
        have this functionality readily available. Do note that a check which has this property set
        to true, will log violations only for the first not-tight HTML tag found. To allow a check
        to skip processing of javadocs with non-tight HTML, the
        <code>acceptJavadocWithNonTightHtml</code> method in class <code>AbstractJavadocCheck</code> can be
        overridden in the check. The following example illustrates how to use this property.
      </p>

      
<p>
        Input:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-text">
/**
  * &lt;body&gt;
  * &lt;p&gt; This class is only meant for testing. &lt;/p&gt;
  * &lt;p&gt; This p tag is not closed. It is non-tight. Will lead to violations if
  * &lt;tt&gt;violateExecutionOnNonTightHtml&lt;/tt&gt; is set to true for the check.
  * &lt;li&gt;tight li tag &lt;p&gt;non-tight p tag, but only the 1st non-tight tag is logged in violation&lt;/li&gt;
  * &lt;/body&gt;
  */
 public class Test {
     /**
      &lt;p&gt;&lt;p&gt;
      paraception. Will result in a violation from the &lt;tt&gt;JavadocParagraph&lt;/tt&gt; check due to
      redundant tags.
      &lt;/p&gt;&lt;/p&gt;
      */
     private int field1;

     /**&lt;tr&gt; Zero &lt;/p&gt; nesting despite `tr` is closed &lt;/tr&gt;*/
     private int field2;

     /**
      * &lt;p&gt; this paragraph is closed and would be nested in javadoc tree &lt;/p&gt;
      * &lt;li&gt; this list has an &lt;p&gt; unclosed para, but still the list would get nested &lt;/li&gt;
      */
     private int field3;

     /**
      * &lt;li&gt; Complete &lt;p&gt; nesting &lt;/p&gt; &lt;/li&gt;
      */
     private int field4;
}

      </code></pre></div>

      
<p>
        Output with <code>violateExecutionOnNonTightHtml</code> set to false:
      </p>

      
<div class="wrapper">
        
<table class="table table-striped">
          
<tr class="a">
            
<td>
              
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;!DOCTYPE module PUBLIC
          &quot;-//Checkstyle//DTD Checkstyle Configuration 1.3//EN&quot;
          &quot;https://checkstyle.org/dtds/configuration_1_3.dtd&quot;&gt;
&lt;module name=&quot;Checker&quot;&gt;
  &lt;module name=&quot;TreeWalker&quot;&gt;
    &lt;module name=&quot;JavadocParagraph&quot;&gt;
      &lt;property name=&quot;violateExecutionOnNonTightHtml&quot; value=&quot;false&quot;/&gt;
    &lt;/module&gt;
  &lt;/module&gt;
&lt;/module&gt;
              </code></pre></div>
            </td>

            
<td>
              
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
Starting audit...
[ERROR] Test.java:11: Redundant &lt;p&gt; tag. [JavadocParagraph]
Audit done.
Checkstyle ends with 1 errors.
              </code></pre></div>
            </td>
          </tr>
        </table>
      </div>

      
<p>
        Output with <code>violateExecutionOnNonTightHtml</code> set to true:
      </p>

      
<div class="wrapper">
        
<table class="table table-striped">
          
<tr class="a">
            
<td>
              
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;!DOCTYPE module PUBLIC
          &quot;-//Checkstyle//DTD Checkstyle Configuration 1.3//EN&quot;
          &quot;https://checkstyle.org/dtds/configuration_1_3.dtd&quot;&gt;
&lt;module name=&quot;Checker&quot;&gt;
  &lt;module name=&quot;TreeWalker&quot;&gt;
    &lt;module name=&quot;JavadocParagraph&quot;&gt;
      &lt;property name=&quot;violateExecutionOnNonTightHtml&quot; value=&quot;true&quot;/&gt;
    &lt;/module&gt;
  &lt;/module&gt;
&lt;/module&gt;
              </code></pre></div>
            </td>

            
<td>
              
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
Starting audit...
[ERROR] Test.java:4: Unclosed HTML tag found: p [JavadocParagraph]
[ERROR] Test.java:11: Redundant &lt;p&gt; tag. [JavadocParagraph]
[ERROR] Test.java:11: Unclosed HTML tag found: p [JavadocParagraph]
[ERROR] Test.java:18: Unclosed HTML tag found: tr [JavadocParagraph]
[ERROR] Test.java:23: Unclosed HTML tag found: p [JavadocParagraph]
Audit done.
Checkstyle ends with 5 errors.
              </code></pre></div>
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section><a id="Checkstyle_SDK_GUI"></a>
<h1>Checkstyle SDK GUI</h1>
      
<p>
       The Checkstyle GUI provides us with a way to show javadoc trees in java files. To run it,
       use
      </p>
      
<div class="wrap-content">
        
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
          java -cp checkstyle-10.23.0-all.jar com.puppycrawl.tools.checkstyle.gui.Main
        </code></pre></div>
      </div>
      
<p>
       and choose &quot;JAVA WITH JAVADOC MODE&quot; in dropdown list in bottom of frame.
      </p>
      
<p>
       Now you can see a parsed javadoc tree as a child of comment block.
      </p>
      
<p>
        <span class="wrapper block">
          <img src="images/gui_javadoc_screenshot.png" alt="screenshot" />
        </span>
      </p>
      
<p>
       Notice that only files with &quot;.java&quot; extension can be opened.
      </p>
      
<p>
        For detail reference you can see
        <a href="./writingchecks.html#The_Checkstyle_SDK_Gui">
          Checkstyle GUI documentation
        </a>.
      </p>
    </section>

    <section><a id="Customize_token_types_in_Javadoc_Checks"></a>
<h1>Customize token types in Javadoc Checks</h1>
      
<p>
        Java checks are controlled by methods <a href="writingchecks.html#Understanding_token_sets">
          setTokens(), getDefaultTokens(), getAccessibleTokens(), getRequiredTokens(). </a>
        JavaDoc checks use the same model plus 4 additional methods for Javadoc tokens.
        As Java AST and Javadoc AST are not bound,
        it is highly recommended for Javadoc checks to not use customization of java tokens and
        except to be executed only on javadoc tokens.
      </p>
      
<p>
        There are four methods in the AbstractJavadocCheck class to control the processed
        <a href="apidocs/index.html">JavadocTokenTypes</a> -
        one setter
        <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#setJavadocTokens-java.lang.String...-">
        setJavadocTokens()</a>, which is used to define a custom set (which is different
        from the default one) of the processed JavadocTokenTypes via config file and
        three getters, which have to be overridden:
        <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getDefaultJavadocTokens--">
        getDefaultJavadocTokens()</a>,
        <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getAcceptableJavadocTokens--">
        getAcceptableJavadocTokens()</a>,
        <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getRequiredJavadocTokens--">
        getRequiredJavadocTokens()</a>.
      </p>

      
<ul>

        
<li>
          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#setJavadocTokens-java.lang.String...-">
          setJavadocTokens()</a> - method then define actual set of tokens to run on.
        </li>
        
<li>
          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getDefaultJavadocTokens--">
          getDefaultJavadocTokens()</a> - returns a set of JavadocTokenTypes which are processed in
          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#visitToken-com.puppycrawl.tools.checkstyle.api.DetailAST-">
          visitToken()</a> method by default.
        </li>

        
<li>
          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getRequiredJavadocTokens--">
          getRequiredJavadocTokens()</a> - returns a set of JavadocTokenTypes which Check must
          be subscribed to for a valid execution. If the user wants to specify a custom set of
          JavadocTokenTypes then this set must contain all the JavadocTokenTypes from
          RequiredJavadocTokens.
        </li>

        
<li>
          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#getAcceptableJavadocTokens--">
          getAcceptableJavadocTokens()</a> - returns a set, which contains all the
          JavadocTokenTypes that can be processed by the check. Both DefaultJavadocTokens and
          RequiredJavadocTokens and any custom set of JavadocTokenTypes are subsets of
          AcceptableJavadocTokens.
        </li>

      </ul>
    </section>

    <section><a id="Integrating_new_Javadoc_Check"></a>
<h1>Integrating new Javadoc Check</h1>
      
<p>
      Javadoc Checks as well as regular Checks extend
        <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html">
        AbstractCheck</a> class. So integrating a new Javadoc Check is similar to
        <a href="writingchecks.html#Integrating_Checks">integrating other Checks</a>.
      </p>
    </section>

    <section><a id="Declare_check.27s_external_resource_locations"></a>
<h1>Declare check's external resource locations</h1>
      
<p>
      See <a href="writingchecks.html#Declare_check.27s_external_resource_locations">Declare check's
      external resource locations</a>.
      </p>
    </section>

    <section><a id="Examples_of_Javadoc_Checks"></a>
<h1>Examples of Javadoc Checks</h1>
      
<p>
        The best source knowledge on how to write Javadoc Checks
        can be taken from
        <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fjava+repo%3Acheckstyle%2Fcheckstyle+%22extends+AbstractJavadocCheck%22" class="externalLink">
          existing Checks
        </a>.
      </p>
    </section>

    <section><a id="Javadoc_parser_behavior_for_current_HTML_version_and_new_HTML_version"></a>
<h1>Javadoc parser behavior for current HTML version and new HTML version</h1>
      
<p>
      This section shows how the parser should/will behave during parsing of the current HTML
      version and any new HTML version. The current version is HTML4, a new version that needs to
      be supported is HTML5.
      GeneralToken - mean that after parsing there will be general AstToken - HTML_TAG.
      SpecialToken - mean that after parsing there will be special AstToken - PARAGRAPH, .... .
      </p>
      
<p><b>Tags with optional (omittable) end tag:</b></p>
      
<div class="wrapper">
        
<table class="table table-striped" style="table-layout: fixed;">
          
<tr class="a">
            
<th>Input</th>
            
<th>Current standard (HTML4)</th>
            
<th>Current standard with hasUnclosedTag flag</th>
            
<th>After parser update for new standard (HTML5)</th>
            
<th>After parser update for new standard with hasUnclosedTag flag</th>
          </tr>
          
<tr class="b">
            
<td>&lt;p&gt;text&lt;/p&gt;</td>
            
<td>No errors, Nested tree, SpecialToken</td>
            
<td>No errors, Nested tree, SpecialToken, hasUnclosedTag=false</td>
            
<td>No errors, Nested tree, SpecialToken</td>
            
<td>No errors, Nested tree, SpecialToken, hasUnclosedTag=false</td>
          </tr>
          
<tr class="a">
            
<td>&lt;p&gt;text</td>
            
<td>No errors, Non-nested tree, SpecialToken</td>
            
<td>No errors, Non-nested tree, SpecialToken, hasUnclosedTag=true</td>
            
<td>No errors, Non-nested tree, SpecialToken</td>
            
<td>No errors, Non-nested tree, SpecialToken, hasUnclosedTag=true</td>
          </tr>
          
<tr class="b">
            
<td>
              &lt;rb&gt;text&lt;/rb&gt;
              <br /><i>New HTML5 tag with optional (omittable) end tag</i>
            </td>
            
<td>No errors, Nested tree, GeneralToken</td>
            
<td>No errors, Nested tree, GeneralToken, hasUnclosedTag=false</td>
            
<td>No errors, Nested tree, SpecialToken</td>
            
<td>No errors, Nested tree, SpecialToken, hasUnclosedTag=false</td>
          </tr>
          
<tr class="a">
            
<td>
              &lt;rb&gt;text
              <br /><i>New HTML5 tag with optional (omittable) end tag</i>
            </td>
            
<td>Parse error</td>
            
<td>Parse error</td>
            
<td>No errors, Non-nested tree, SpecialToken</td>
            
<td>No errors, Non-nested tree, SpecialToken, hasUnclosedTag=true</td>
          </tr>
          
<tr class="b">
            
<td>
              &lt;qwerty&gt;text&lt;/qwerty&gt;
              <br /><i>Unknown HTML tag</i>
            </td>
            
<td>No errors, Nested tree, GeneralToken</td>
            
<td>No errors, Nested tree, GeneralToken, hasUnclosedTag=false</td>
            
<td>No errors, Nested tree, GeneralToken</td>
            
<td>No errors, Nested tree, GeneralToken, hasUnclosedTag=false</td>
          </tr>
          
<tr class="a">
            
<td>
              &lt;qwerty&gt;text
              <br /><i>Unknown HTML tag</i>
            </td>
            
<td>Parse error</td>
            
<td>Parse error</td>
            
<td>Parse error</td>
            
<td>Parse error</td>
          </tr>
        </table>
      </div>
      <br />
      
<p><b>Void tags:</b></p>
      
<p>
      Note: &quot;Nested&quot;/&quot;Non-Nested&quot; is not applicable for this type of tags - all of them are looks
      like Non-Nested. Flas &quot;hasUnclosedTag&quot; is &quot;false&quot; for all cases.
      </p>
      
<div class="wrapper">
        
<table class="table table-striped" style="table-layout: fixed;">
          
<tr class="a">
            
<th>Input</th>
            
<th>Current standard (HTML4)</th>
            
<th>After parser update for new standard (HTML5)</th>
          </tr>
          
<tr class="b">
            
<td>&lt;br/&gt;</td>
            
<td>No errors, SpecialToken</td>
            
<td>No errors, SpecialToken</td>
          </tr>
          
<tr class="a">
            
<td>&lt;br&gt;</td>
            
<td>No errors, SpecialToken</td>
            
<td>No errors, SpecialToken</td>
          </tr>
          
<tr class="b">
            
<td>
              &lt;embed/&gt;
              <br /><i>New HTML5 tag</i>
            </td>
            
<td>No errors, GeneralToken</td>
            
<td>No errors, SpecialToken</td>
          </tr>
          
<tr class="a">
            
<td>
              &lt;embed&gt;
              <br /><i>New HTML5 tag</i>
            </td>
            
<td>Parse Error</td>
            
<td>No errors, SpecialToken</td>
          </tr>
          
<tr class="b">
            
<td>
              &lt;basefont/&gt;
              <br /><i>Supported in HTML4. Not supported tag in HTML5</i>
            </td>
            
<td>No errors, SpecialToken</td>
            
<td>No errors, SpecialToken</td>
          </tr>
          
<tr class="a">
            
<td>
              &lt;basefont&gt;
              <br /><i>Supported in HTML4. Not supported tag in HTML5</i>
            </td>
            
<td>No errors, SpecialToken</td>
            
<td>No errors, SpecialToken</td>
          </tr>
          
<tr class="b">
            
<td>
              &lt;qwerty/&gt;
              <br /><i>Unknown HTML tag</i>
            </td>
            
<td>No errors, GeneralToken</td>
            
<td>No errors, GeneralToken</td>
          </tr>
          
<tr class="a">
            
<td>
              &lt;qwerty&gt;
              <br /><i>Unknown HTML tag</i>
            </td>
            
<td>Parse Error</td>
            
<td>Parse Error</td>
          </tr>
        </table>
      </div>
    </section>

  
        </main>
      </div>
    </div>
    <hr/>
    <footer>
      <div class="container-fluid">
        <div class="row-fluid">
            <p>©      2001–2025
</p>
        </div>
      </div>
    </footer>
  </body>
</html>