- Here you can find instructions of importing and debugging the project for IDEs:
+ Here you can find instructions on importing and debugging the project for IDEs: Eclipse IDE NetBeans IDE IntelliJ IDEA IDE
diff --git a/src/xdocs/config_system_properties.xml b/src/xdocs/config_system_properties.xml
index 42672ab5da4..05db7f6e4bc 100644
--- a/src/xdocs/config_system_properties.xml
+++ b/src/xdocs/config_system_properties.xml
@@ -28,18 +28,18 @@
The property checkstyle.enableExternalDtdLoad
- defines ability use custom DTD files in config and load them from some location.
+ defines the ability to use custom DTD files in config and load them from some location.
The property type
is boolean and defaults
to false. Disabled by default due to security concerns.
- The following is an example of include xml files content in xml by ENTITY feature
- to let keep common part of configs in single file and composite main config
- by few smaller parts.
+ The following is an example of including the contents of other xml files by using the
+ ENTITY feature to keep common parts of configs in a single file and then creating
+ composite configs from smaller parts.
- Imagine we want to define for test sources a bit different requirements
+ Imagine we want to define slightly different requirements for test sources
than for main code.
- All functional changes in project should have registered issue and wide explanation in it.
- Issue number has to be referenced in git commit message, see format below.
+ All functional changes in the project should have a registered issue and detailed
+ explanation in it. The Issue number has to be referenced in the git commit message,
+ see format below.
- Project is following general maven layout and phases for build.
+ The project is following a general maven layout and phases for its build.
Generated jars will be in folder target.
@@ -87,8 +88,8 @@
- The developer team of checkstyle is really a lazy bunch of
- people. We try to avoid work as best as we can, but most of all
+ The developer team of checkstyle is a really lazy bunch of
+ people. We try to avoid work as best as we can, but most of all
we try to avoid working on bugs that are reported by end users.
@@ -107,7 +108,7 @@
mvn test jacoco:restore-instrumented-classes jacoco:report@default-report.
- Check results on report target/site/jacoco/index.html in project home folder.
+ Check the results on the report in target/site/jacoco/index.html in project home folder.
@@ -127,7 +128,7 @@
- The last step of verification that all works fine please do testing of your
+ For the last step of verification, so that everything works fine, please do testing of your
functionality on any open-source project (Spring, Hibernate, ....).
Here is how to do it by
Checkstyle is not using Semantic Versioning
- due to reason that is explained at
+ due to the reason explained at
issue #3709.
@@ -167,10 +168,10 @@
- Checkstyle currently is confirmed to be build by all JDKs from 11 through 17.
+ Checkstyle currently is confirmed to be buildable by all JDKs from 11 through 17.
Most recent JDKs may be supported. Please
report an issue
- if there is any problems with most recent JDKs.
+ if there are any problems with most recent JDKs.
@@ -229,7 +230,7 @@
- There are other projects that provide additional checks
+ There are other projects that provide additional checks:
diff --git a/src/xdocs/writingchecks.xml b/src/xdocs/writingchecks.xml
index 2386287b0ea..a88d8ecabbb 100644
--- a/src/xdocs/writingchecks.xml
+++ b/src/xdocs/writingchecks.xml
@@ -540,7 +540,7 @@ public class MethodLimitCheck extends AbstractCheck
- Detecting violation is one thing. Presenting them to the user is
+ Detecting violations is one thing. Presenting them to the user is
another. To do that, the Check base class provides several log
methods, the simplest of them being Check.log(String). In your
Check you can simply use a verbatim violation string as the argument, i.e.
diff --git a/src/xdocs/writingjavadocchecks.xml.vm b/src/xdocs/writingjavadocchecks.xml.vm
index ed6b7d00cdc..3041d8ccfb3 100644
--- a/src/xdocs/writingjavadocchecks.xml.vm
+++ b/src/xdocs/writingjavadocchecks.xml.vm
@@ -99,15 +99,16 @@ public class MyClass {
- Javadoc by specification could contain any HTML tags that let user generate content he needs.
- All tags are copied as is to result javadoc html pages by Sun/Oracle javadoc tool.
- All bad formatting is responsibility of user and web-browser. To validate Checkstyle to parse
- input to predictable structure - Abstract Syntax Tree(AST). It is very difficult to parse
- free style format, so input text need to follow some format, so limitation appears.
+ Javadoc by specification could contain any HTML tags that lets users generate the content
+ they need. All tags are copied as is to result in javadoc html pages by the Sun/Oracle
+ javadoc tool. All bad formatting is the responsibility of user and web-browser. To validate
+ Checkstyle it needs to parse input into a predictable structure - Abstract Syntax Tree(AST).
+ Since it is very difficult to parse a free style format, input text needs to follow some
+ format, therefore limitations apply.
The comment should be written in Tight-HTML
- to build nested AST Tree that most Checks expect.
+ to build nested ASTs that most Checks expect.
For more details about parsing of HTML into AST read
@@ -127,14 +128,14 @@ public class MyClass {
The only exceptions are HTML 4 tags whose end tag is optional (omittable) by
HTML specification (example is
TR), so,
- Checkstyle won't show error about missing end tag, however,
- it leads to broken Tight-HTML structure and as a result
- leads to not-nested content of the HTML tags in Abstract Syntax Tree of the Javadoc comment.
+ 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.
- In other words, if HTML tags are not closed Javadoc grammar cannot determine content
+ In other words, if HTML tags are not closed Javadoc, grammar cannot determine content
of these tags, so structure of the parse tree will not be nested like it is while using
- Tight-HTML code. It is done just to not fail on every
- Javadoc comment, because there are tons of using unclosed tags, etc.
+ Tight-HTML code. This is done just to not fail on every
+ Javadoc comment, because a ton of unclosed tags are used, etc.
Other rules:
@@ -157,7 +158,7 @@ public class MyClass {
Principle of writing Javadoc Checks is similar to writing regular Checks. You just extend
- another abstract class and use another token types.
+ another abstract class and use another set of token types.
To start implementing new Check create a new class and extend
- Main Java grammar skips any whitespaces and newlines, so in Java Abstract Syntax Tree there
- are no whitespace/newline nodes. In Javadoc comment every whitespace matters, and Javadoc
- Checks need all those whitespaces and newline nodes to verify format and content of the
- Javadoc comment. Because of that Javadoc grammar includes all whitespaces, newlines to
- the parse tree
+ The main Java grammar skips any whitespaces and newlines, so there are no
+ whitespace/newline nodes in Java Abstract Syntax Tree.
+ there are no whitespace/newline nodes. In Javadoc comments every whitespace matters, and
+ Javadoc Checks need all those whitespaces and newline nodes to verify format and content of
+ the Javadoc comment. Because of that, the Javadoc grammar includes all whitespaces, and
+ newlines to the parse tree
(WS,
NEWLINE).
@@ -224,8 +226,8 @@ public class MyClass {
- Checkstyle can print Abstract Syntax Tree for Java and Javadoc trees. You need to run
- checkstyle jar file with -J argument, providing java file.
+ Checkstyle can print Abstract Syntax Trees for Java and Javadoc trees. You need to run the
+ checkstyle jar file with the -J argument, providing a java file.
For example, here is MyClass.java file:
CLASS_DEF [5:0]
`--RCURLY -> } [7:0]
]]>
- As you see very small java file transforms to a huge Abstract Syntax Tree, because that is
- the most detailed tree including all components of the java file: classes, methods,
+ As you see, a very small java file transforms into a huge Abstract Syntax Tree, because that
+ is the most detailed tree including all components of the java file: classes, methods,
comments, etc.
- In most cases while developing Javadoc Check, you need to only parse the tree of the exact
- Javadoc comment. To do that just copy Javadoc comment to separate file and remove /**
- at the beginning and */ at the end. After that, run checkstyle with -j
- argument.
+ In most cases while developing Javadoc Checks, you need to only parse the tree of the exact
+ Javadoc comment. To do that just copy the Javadoc comment to a separate file and remove
+ /** at the beginning and */ at the end. After that, run checkstyle with the
+ -j argument.
MyJavadocComment.javadoc file:
JAVADOC [0:0]
- As you already know Javadoc parse tree is a result of parsing block comment. There is a
- method to get the original block comment from Javadoc Check.
- You may need this block comment to check its position or something else in java
+ As you already know the Javadoc parse tree is a result of parsing the 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 or something else in a java
DetailAST tree.
- For example, to write a JavadocCheck that verifies @param tags in Javadoc comment of
- a method definition, you also need all method's parameter names. To get method
- definition AST you should access java
+ 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 java
DetailAST tree
- from javadoc Check. For this purpose use
+ from a javadoc Check. For this purpose use the
getBlockCommentAst()
- method that returns
+ method that returns a
DetailAST node.
@@ -396,7 +398,7 @@ class MyCheck extends AbstractJavadocCheck {
.
- If Checkstyle meets unknown tag (for example HTML5 tag)
- it doesn't fail and parses this tag as
+ If Checkstyle meets an unknown tag (for example HTML5 tag)
+ it doesn't fail and parses this tag as a
HTML_TAG
Javadoc token type.
- Just follow Tight-HTML rules to make
- Checkstyle javadoc parser make nested AST, even though tags are unknown.
+ Just follow Tight-HTML rules to make the
+ Checkstyle javadoc parser create nested ASTs, even though tags are unknown.
@@ -470,8 +472,8 @@ JAVADOC -> JAVADOC [0:0]
- Here is what you get if unknown tag doesn't have matching end tag (for example, HTML5 tag
- <audio>):
+ Here is what you get if the unknown tag doesn't have a matching end tag (for example, HTML5
+ tag <audio>):
Input:
<audio>test
Output:
@@ -483,18 +485,18 @@ JAVADOC -> JAVADOC [0:0]
- As you see Javadoc parser prints error and doesn't build AST if unknown HTML tag doesn't
- have matching end tag. If that a case please create an issue against Checkstyle to
- upgrade parser.
+ 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 upgrade the parser.
There are also HTML tags that are marked as "Not supported in HTML5"
(HTML Element Reference).
- Checkstyle Javadoc parser can parse those tags too if they are written in
+ The checkstyle Javadoc parser can parse those tags too if they are written in
Tight-HTML.
- Example.
+ Example:
Input:
JAVADOC [0:0]
- 1) Unclosed paragraph HTML tag. As you see in the tree, content of the paragraph tag
- is not nested to this tag.
- That is because HTML tags are not closed by pair tag </p>, and Checkstyle
+ 1) Unclosed paragraph HTML tag. As you see in the tree, the content of the paragraph
+ tag is not nested to this tag.
+ That is because HTML tags are not closed by pair tags </p>, and Checkstyle
requires Tight-HTML code to predictably parse
Javadoc comments.
- 2) Here is correct version with open and closed HTML tags.
+ 2) Here is a correct version with open and closed HTML tags.
@@ -619,12 +621,12 @@ JAVADOC -> JAVADOC [0:0]
- Checks can also be configured to log violation on encountering non-tight HTML tags.
- violateExecutionOnNonTightHtml property can be used for this purpose in the checks
- that support it. A custom check needs to extend AbstractJavadocCheck for having
- this functionality readily available. Do note that a check which has this property set to
- true will log violation only for the first not-tight HTML tag found. To allow a check to
- skip processing of javadocs with non-tight HTML, method
+ Checks can also be configured to log violations upon encountering non-tight HTML tags.
+ The violateExecutionOnNonTightHtml property can be used for this purpose in the
+ checks that support it. A custom check needs to extend AbstractJavadocCheck 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, method
acceptJavadocWithNonTightHtml in class AbstractJavadocCheck can be
overridden in the check. The following example illustrates how to use this property.
@@ -743,7 +745,7 @@ Checkstyle ends with 5 errors.
- Checkstyle GUI allows to show javadoc tree in java files. To run in use
+ Checkstyle GUI allows to show javadoc trees in java files. To run it, use
@@ -754,7 +756,7 @@ Checkstyle ends with 5 errors.
and choose "JAVA WITH JAVADOC MODE" in dropdown list in bottom of frame.
- Now you can see parsed javadoc tree as child of comment block.
+ Now you can see a parsed javadoc tree as a child of comment block.
@@ -774,15 +776,15 @@ Checkstyle ends with 5 errors.
- Java checks controlled by method
+ Java checks are controlled by methods
setTokens(), getDefaultTokens(), getAccessibleTokens(), getRequiredTokens().
- 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.
+ JavaDoc checks use the same model plus 4 additional methods for Javadoc tokens.
+ As Java AST and Javadoc AST are not binded,
+ it is highly recommended for Javadoc checks to not use customization of java tokens and
+ except to be executed only on javadoc tokens.
@@ -847,8 +849,8 @@ Checkstyle ends with 5 errors.
- The best source knowledge about how to write Javadoc Checks
- could be taken from
+ The best source knowledge on how to write Javadoc Checks
+ can be taken from
existing Checks
.
@@ -857,9 +859,9 @@ Checkstyle ends with 5 errors.
- This section shows how parser should/will behave during parsing of current HTML version
- and any new HTML version. Current version is HTML4, new version that need to be supported
- is HTML5.
+ 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, .... .