From c2b692a5710a11c48ad3de7a1aef5dfd26b90a2c Mon Sep 17 00:00:00 2001 From: AdoraMel <164820212+AdoraMel@users.noreply.github.com> Date: Thu, 28 Mar 2024 21:36:01 +0100 Subject: [PATCH] doc: improve grammar, spelling, and punctuation --- src/xdocs/beginning_development.xml | 2 +- src/xdocs/config_system_properties.xml | 10 +- src/xdocs/contributing.xml | 17 +-- src/xdocs/index.xml.vm | 17 +-- src/xdocs/writingchecks.xml | 2 +- src/xdocs/writingjavadocchecks.xml.vm | 154 +++++++++++++------------ 6 files changed, 103 insertions(+), 99 deletions(-) diff --git a/src/xdocs/beginning_development.xml b/src/xdocs/beginning_development.xml index c82d32d259b..b1055295df0 100644 --- a/src/xdocs/beginning_development.xml +++ b/src/xdocs/beginning_development.xml @@ -43,7 +43,7 @@

- 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.

diff --git a/src/xdocs/contributing.xml b/src/xdocs/contributing.xml index 8e9c4c8edc7..3efaec3a9c0 100644 --- a/src/xdocs/contributing.xml +++ b/src/xdocs/contributing.xml @@ -55,12 +55,13 @@

- 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.

- To report issue please follow our best practices page - + To report an issue please follow our best practices page - How to report an issue? ( How to report a bug?)

@@ -68,7 +69,7 @@

- 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

Current site contains documentation only for latest, released version. - We only support this latest version. We highly recommend read latest documentation first. + We only support this latest version. We highly recommend reading the latest documentation + first.
However, you might need documentation for previous releases because you are still using - an older version and latest version describe some features that does not work for you. + an older version and the latest version describes some features that don't work for you.
You can find documentation for most old versions using a URL format like https://checkstyle.sourceforge.io/version/X.X where "X.X" is the version number.
@@ -99,7 +100,7 @@

- Checkstyle is following own view of + Checkstyle is following its own view of Hybrid Romantic and Semantic Versioning: This is in the form of "First.Second.Third"

@@ -107,7 +108,7 @@ First digit is representing Romantic version. When it is the only number increasing, the maintainers marked it as a noticeably large breaking compatibility - or major conceptual change occurred from their perspective.
+ or major conceptual change which occurred from their perspective.
Second digit is Semantic version which is a combination of major and minor. When it is the only number increasing, it means that either some breaking compatibility happened @@ -117,7 +118,7 @@

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

- Java grammar parses java file base on Java language specifications. So, there are + Java grammar parses java file based on Java language specifications. So, there are singleline comments and multiline/block comments in it. - Java compiler doesn't know about Javadoc because it is just a multiline comment. - To parse multiline comment as a Javadoc comment, checkstyle has special Parser + The Java compiler doesn't know about Javadoc because it is just a multiline comment. + To parse a multiline comment as a Javadoc comment, checkstyle has a special Parser that is based on ANTLR Javadoc grammar. So, it's supposed to process block comments that start with Javadoc Identifier and parse them to Abstract Syntax Tree (AST).

@@ -211,11 +212,12 @@ public class MyClass { objects.

- 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 { .

- HTML4 is picked just to have a list of elements whose end tag is optional(omittable) and a + HTML4 was made to just have a list of elements whose end tag is optional(omittable) and a list of void elements (also known as empty html tags, for example BR @@ -415,22 +417,22 @@ class MyCheck extends AbstractJavadocCheck {

To make Checkstyle support HTML5 tags whose end tag is optional (omittable) and HTML5 void - elements we should update Javadoc Parser because each element that breaks - Tight-HTML rules have to be defined in Javadoc grammar. - In the future, we should update Javadoc grammar if those tag lists extend (new tags, + elements, we should update the Javadoc Parser because each element that breaks + Tight-HTML rules has to be defined in Javadoc grammar. + In the future, we should update the Javadoc grammar if those tag lists extend (new tags, new HTML standard, etc.). (We already have an issue on updating Javadoc grammar to HTML5)

- 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]

@@ -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.

- There are four methods in AbstractJavadocCheck class to control the processed + There are four methods in the AbstractJavadocCheck class to control the processed JavadocTokenTypes - one setter @@ -833,7 +835,7 @@ Checkstyle ends with 5 errors.

Javadoc Checks as well as regular Checks extend - AbstractCheck class. So integrating new Javadoc Check is similar to + AbstractCheck class. So integrating a new Javadoc Check is similar to integrating other Checks.

@@ -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, .... .

- 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.