Update documentation

TRAVIS_JOB_NUMBER=3225.1
TRAVIS_COMMIT_RANGE=dfd5b7b8865d...4cc34459c1ee

docs/_data/sidebars/pmd_sidebar.yml

@@ -121,6 +121,9 @@ entries:
         - title: Design
           output: web, pdf
           url: /pmd_rules_apex_design.html
+        - title: Documentation
+          output: web, pdf
+          url: /pmd_rules_apex_documentation.html
         - title: Error Prone
           output: web, pdf
           url: /pmd_rules_apex_errorprone.html

docs/pages/pmd/rules/apex.md

@@ -44,6 +44,12 @@ folder: pmd/rules
 *   [StdCyclomaticComplexity](pmd_rules_apex_design.html#stdcyclomaticcomplexity): Complexity directly affects maintenance costs is determined by the number of decision points in a...
 *   [TooManyFields](pmd_rules_apex_design.html#toomanyfields): Classes that have too many fields can become unwieldy and could be redesigned to have fewer field...
 
+## Documentation
+
+{% include callout.html content="Rules that are related to code documentation." %}
+
+*   [ApexDoc](pmd_rules_apex_documentation.html#apexdoc): This rule validates that: ApexDoc comments are present for classes, methods, and properties that ...
+
 ## Error Prone
 
 {% include callout.html content="Rules to detect constructs that are either broken, extremely confusing or prone to runtime errors." %}

docs/pages/pmd/rules/apex/documentation.md

@@ -0,0 +1,59 @@
+---
+title: Documentation
+summary: Rules that are related to code documentation.
+permalink: pmd_rules_apex_documentation.html
+folder: pmd/rules/apex
+sidebaractiveurl: /pmd_rules_apex.html
+editmepath: ../pmd-apex/src/main/resources/category/apex/documentation.xml
+keywords: Documentation, ApexDoc
+language: Apex
+---
+<!-- DO NOT EDIT THIS FILE. This file is generated from file ../pmd-apex/src/main/resources/category/apex/documentation.xml. -->
+## ApexDoc
+
+**Since:** PMD 6.8.0
+
+**Priority:** Medium (3)
+
+This rule validates that:
+
+* ApexDoc comments are present for classes, methods, and properties that are public or global, excluding
+overrides and test classes (as well as the contents of test classes).
+* ApexDoc comments should contain @description.
+* ApexDoc comments on non-void, non-constructor methods should contain @return.
+* ApexDoc comments on void or constructor methods should not contain @return.
+* ApexDoc comments on methods with parameters should contain @param for each parameter, in the same
+order as the method signature.
+
+Method overrides and tests are both exempted from having ApexDoc.
+
+**This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.apex.rule.documentation.ApexDocRule](https://github.com/pmd/pmd/blob/master/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/documentation/ApexDocRule.java)
+
+**Example(s):**
+
+``` java
+/**
+ * @description Hello World
+ */
+public class HelloWorld {
+    /**
+     * @description Bar
+     * @return Bar
+     */
+    public Object bar() { return null; }
+}
+```
+
+**This rule has the following properties:**
+
+|Name|Default Value|Description|Multivalued|
+|----|-------------|-----------|-----------|
+|cc\_categories|Style|Code Climate Categories|yes. Delimiter is '\|'.|
+|cc\_remediation\_points\_multiplier|1|Code Climate Remediation Points multiplier|no|
+|cc\_block\_highlighting|false|Code Climate Block Highlighting|no|
+
+**Use this rule by referencing it:**
+``` xml
+<rule ref="category/apex/documentation.xml/ApexDoc" />
+```
+

docs/pages/pmd/rules/java.md

@@ -16,6 +16,7 @@ folder: pmd/rules
 *   [AccessorMethodGeneration](pmd_rules_java_bestpractices.html#accessormethodgeneration): When accessing a private field / method from another class, the Java compiler will generate a acc...
 *   [ArrayIsStoredDirectly](pmd_rules_java_bestpractices.html#arrayisstoreddirectly): Constructors and methods receiving arrays should clone objects and store the copy.This prevents f...
 *   [AvoidPrintStackTrace](pmd_rules_java_bestpractices.html#avoidprintstacktrace): Avoid printStackTrace(); use a logger call instead.
+*   [AvoidReassigningLoopVariables](pmd_rules_java_bestpractices.html#avoidreassigningloopvariables): Reassigning loop variables can lead to hard-to-find bugs. Prevent or limit how these variables ca...
 *   [AvoidReassigningParameters](pmd_rules_java_bestpractices.html#avoidreassigningparameters): Reassigning values to incoming parameters is not recommended.  Use temporary local variables inst...
 *   [AvoidStringBufferField](pmd_rules_java_bestpractices.html#avoidstringbufferfield): StringBuffers/StringBuilders can grow considerably, and so may become a source of memory leaksif ...
 *   [AvoidUsingHardCodedIP](pmd_rules_java_bestpractices.html#avoidusinghardcodedip): Application with hard-coded IP addresses can become impossible to deploy in some cases.Externaliz...
@@ -23,6 +24,7 @@ folder: pmd/rules
 *   [ConstantsInInterface](pmd_rules_java_bestpractices.html#constantsininterface): Avoid constants in interfaces. Interfaces should define types, constants are implementation detai...
 *   [DefaultLabelNotLastInSwitchStmt](pmd_rules_java_bestpractices.html#defaultlabelnotlastinswitchstmt): By convention, the default label should be the last label in a switch statement.
 *   [ForLoopCanBeForeach](pmd_rules_java_bestpractices.html#forloopcanbeforeach): Reports loops that can be safely replaced with the foreach syntax. The rule considers loops overl...
+*   [ForLoopVariableCount](pmd_rules_java_bestpractices.html#forloopvariablecount): Having a lot of control variables in a 'for' loop makes it harder to see what range of valuesthe ...
 *   [GuardLogStatement](pmd_rules_java_bestpractices.html#guardlogstatement): Whenever using a log level, one should check if the loglevel is actually enabled, orotherwise ski...
 *   [JUnit4SuitesShouldUseSuiteAnnotation](pmd_rules_java_bestpractices.html#junit4suitesshouldusesuiteannotation): In JUnit 3, test suites are indicated by the suite() method. In JUnit 4, suites are indicatedthro...
 *   [JUnit4TestShouldUseAfterAnnotation](pmd_rules_java_bestpractices.html#junit4testshoulduseafterannotation): In JUnit 3, the tearDown method was used to clean up all data entities required in running tests....

docs/pages/pmd/rules/java/bestpractices.md

@@ -5,7 +5,7 @@ permalink: pmd_rules_java_bestpractices.html
 folder: pmd/rules/java
 sidebaractiveurl: /pmd_rules_java.html
 editmepath: ../pmd-java/src/main/resources/category/java/bestpractices.xml
-keywords: Best Practices, AbstractClassWithoutAbstractMethod, AccessorClassGeneration, AccessorMethodGeneration, ArrayIsStoredDirectly, AvoidPrintStackTrace, AvoidReassigningParameters, AvoidStringBufferField, AvoidUsingHardCodedIP, CheckResultSet, ConstantsInInterface, DefaultLabelNotLastInSwitchStmt, ForLoopCanBeForeach, GuardLogStatement, JUnit4SuitesShouldUseSuiteAnnotation, JUnit4TestShouldUseAfterAnnotation, JUnit4TestShouldUseBeforeAnnotation, JUnit4TestShouldUseTestAnnotation, JUnitAssertionsShouldIncludeMessage, JUnitTestContainsTooManyAsserts, JUnitTestsShouldIncludeAssert, JUnitUseExpected, LooseCoupling, MethodReturnsInternalArray, MissingOverride, OneDeclarationPerLine, PositionLiteralsFirstInCaseInsensitiveComparisons, PositionLiteralsFirstInComparisons, PreserveStackTrace, ReplaceEnumerationWithIterator, ReplaceHashtableWithMap, ReplaceVectorWithList, SwitchStmtsShouldHaveDefault, SystemPrintln, UnusedFormalParameter, UnusedImports, UnusedLocalVariable, UnusedPrivateField, UnusedPrivateMethod, UseAssertEqualsInsteadOfAssertTrue, UseAssertNullInsteadOfAssertTrue, UseAssertSameInsteadOfAssertTrue, UseAssertTrueInsteadOfAssertEquals, UseCollectionIsEmpty, UseVarargs
+keywords: Best Practices, AbstractClassWithoutAbstractMethod, AccessorClassGeneration, AccessorMethodGeneration, ArrayIsStoredDirectly, AvoidPrintStackTrace, AvoidReassigningLoopVariables, AvoidReassigningParameters, AvoidStringBufferField, AvoidUsingHardCodedIP, CheckResultSet, ConstantsInInterface, DefaultLabelNotLastInSwitchStmt, ForLoopCanBeForeach, ForLoopVariableCount, GuardLogStatement, JUnit4SuitesShouldUseSuiteAnnotation, JUnit4TestShouldUseAfterAnnotation, JUnit4TestShouldUseBeforeAnnotation, JUnit4TestShouldUseTestAnnotation, JUnitAssertionsShouldIncludeMessage, JUnitTestContainsTooManyAsserts, JUnitTestsShouldIncludeAssert, JUnitUseExpected, LooseCoupling, MethodReturnsInternalArray, MissingOverride, OneDeclarationPerLine, PositionLiteralsFirstInCaseInsensitiveComparisons, PositionLiteralsFirstInComparisons, PreserveStackTrace, ReplaceEnumerationWithIterator, ReplaceHashtableWithMap, ReplaceVectorWithList, SwitchStmtsShouldHaveDefault, SystemPrintln, UnusedFormalParameter, UnusedImports, UnusedLocalVariable, UnusedPrivateField, UnusedPrivateMethod, UseAssertEqualsInsteadOfAssertTrue, UseAssertNullInsteadOfAssertTrue, UseAssertSameInsteadOfAssertTrue, UseAssertTrueInsteadOfAssertEquals, UseCollectionIsEmpty, UseVarargs
 language: Java
 ---
 <!-- DO NOT EDIT THIS FILE. This file is generated from file ../pmd-java/src/main/resources/category/java/bestpractices.xml. -->
@@ -175,6 +175,66 @@ class Foo {
 <rule ref="category/java/bestpractices.xml/AvoidPrintStackTrace" />
 ```
 
+## AvoidReassigningLoopVariables
+
+**Since:** PMD 6.11.0
+
+**Priority:** Medium (3)
+
+Reassigning loop variables can lead to hard-to-find bugs. Prevent or limit how these variables can be changed.
+
+In foreach-loops, configured by the `foreachReassign` property:
+- `deny`: Report any reassignment of the loop variable in the loop body. _This is the default._
+- `allow`: Don't check the loop variable.
+- `firstOnly`: Report any reassignments of the loop variable, except as the first statement in the loop body.
+            _This is useful if some kind of normalization or clean-up of the value before using is permitted, but any other change of the variable is not._
+
+In for-loops, configured by the `forReassign` property:
+- `deny`: Report any reassignment of the control variable in the loop body. _This is the default._
+- `allow`: Don't check the control variable.
+- `skip`: Report any reassignments of the control variable, except conditional increments/decrements (`++`, `--`, `+=`, `-=`).
+            _This prevents accidental reassignments or unconditional increments of the control variable._
+
+**This rule is defined by the following Java class:** [net.sourceforge.pmd.lang.java.rule.bestpractices.AvoidReassigningLoopVariablesRule](https://github.com/pmd/pmd/blob/master/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/bestpractices/AvoidReassigningLoopVariablesRule.java)
+
+**Example(s):**
+
+``` java
+public class Foo {
+  private void foo() {
+    for (String s : listOfStrings()) {
+      s = s.trim(); // OK, when foreachReassign is "firstOnly" or "allow"
+      doSomethingWith(s);
+
+      s = s.toUpper(); // OK, when foreachReassign is "allow"
+      doSomethingElseWith(s);
+    }
+
+    for (int i=0; i < 10; i++) {
+      if (check(i)) {
+        i++; // OK, when forReassign is "skip" or "allow"
+      }
+
+      i = 5;  // OK, when forReassign is "allow"
+
+      doSomethingWith(i);
+    }
+  }
+}
+```
+
+**This rule has the following properties:**
+
+|Name|Default Value|Description|Multivalued|
+|----|-------------|-----------|-----------|
+|foreachReassign|deny|how/if foreach control variables may be reassigned|no|
+|forReassign|deny|how/if for control variables may be reassigned|no|
+
+**Use this rule by referencing it:**
+``` xml
+<rule ref="category/java/bestpractices.xml/AvoidReassigningLoopVariables" />
+```
+
 ## AvoidReassigningParameters
 
 **Since:** PMD 1.0
@@ -413,6 +473,39 @@ public class MyClass {
 <rule ref="category/java/bestpractices.xml/ForLoopCanBeForeach" />
 ```
 
+## ForLoopVariableCount
+
+**Since:** PMD 6.11.0
+
+**Priority:** Medium (3)
+
+Having a lot of control variables in a 'for' loop makes it harder to see what range of values
+the loop iterates over. By default this rule allows a regular 'for' loop with only one variable.
+
+**This rule is defined by the following XPath expression:**
+``` xpath
+//ForInit/LocalVariableDeclaration[count(VariableDeclarator) > $maximumVariables]
+```
+
+**Example(s):**
+
+``` java
+// this will be reported with the default setting of at most one control variable in a for loop
+for (int i = 0, j = 0; i < 10; i++, j += 2) {
+   foo();
+```
+
+**This rule has the following properties:**
+
+|Name|Default Value|Description|Multivalued|
+|----|-------------|-----------|-----------|
+|maximumVariables|1|A regular for statement will have 1 control variable|no|
+
+**Use this rule by referencing it:**
+``` xml
+<rule ref="category/java/bestpractices.xml/ForLoopVariableCount" />
+```
+
 ## GuardLogStatement
 
 **Since:** PMD 5.1.0