From 92aea351ad38cd244e34d0e185c10d2bb2dd9464 Mon Sep 17 00:00:00 2001
From: Roman Ivanov <ivanov-jr@mail.ru>
Date: Thu, 29 Dec 2016 11:58:23 -0800
Subject: [PATCH] Issue #3672: update documentation about getAcceptableTokens
 for javadoc Checks

---
 src/xdocs/writingjavadocchecks.xml.vm | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/xdocs/writingjavadocchecks.xml.vm b/src/xdocs/writingjavadocchecks.xml.vm
index d6cf8e5ee..54a6d983d 100644
--- a/src/xdocs/writingjavadocchecks.xml.vm
+++ b/src/xdocs/writingjavadocchecks.xml.vm
@@ -496,12 +496,18 @@ java -cp checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.gu
     </section>
 
     <section name="Customize token types in Javadoc Checks">
+      <p>
+        Java checks controlled by method <a href="writingchecks.html#Understanding_token_sets">setTokens(), getDefaultTokens(), getAccessibleTokens(), getRequiredTokens(). </a>
+        JavaDoc checks use the same model plus extra 4 methods for Javadoc tokens.
+        As Java AST and Javadoc AST are not binded.
+        It is highly recommended for Javadoc checks do not use customization of java tokens and expect to be executed only on javadoc tokens.
+      </p>
       <p>
         There are four methods in 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...-">
-        setTokens()</a>, which is used to define a custom set (which is different
+        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--">
@@ -515,19 +521,26 @@ java -cp checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.gu
       <ul>
 
         <li>
-          getDefaultJavadocTokens() - returns a set of JavadocTokenTypes which are processed in
+          <a href="apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html#setJavadocTokens--">
+          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>
-          getRequiredJavadocTokens() - returns a set of JavadocTokenTypes which Check must be subscribed to for
+          <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>
-          getAcceptableJavadocTokens() - returns a set, which contains all the JavadocTokenTypes that
+          <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>