Merge branch 'master' of https://github.com/pmd/pmd into PR-apex

.travis/build-deploy.sh

@@ -3,6 +3,25 @@ set -e
 
 source .travis/common-functions.sh
 
+function push_docs() {
+    if git diff --quiet docs; then
+        echo "No changes in docs..."
+    else
+        echo "Found changes in docs..."
+
+        if [ "$TRAVIS_BRANCH" == "master" ]; then
+            git config user.name "Travis CI (pmd-bot)"
+            git config user.email "adangel+pmd-bot@users.sourceforge.net"
+            git add -A docs
+            git commit -m "Update documentation"
+            git push git@github.com:pmd/pmd.git HEAD:master
+        else
+            echo "Not on master branch, won't commit+push"
+        fi
+    fi
+}
+
+
 VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.5.0:exec | tail -1)
 echo "Building PMD ${VERSION} on branch ${TRAVIS_BRANCH}"
 
@@ -19,6 +38,7 @@ elif travis_isPush; then
     elif [[ "$VERSION" == *-SNAPSHOT ]]; then
         echo "This is a snapshot build"
         ./mvnw deploy -Possrh -B -V
+        push_docs
     else
         # other build. Can happen during release: the commit with a non snapshot version is built, but not from the tag.
         echo "This is some other build, probably during release: commit with a non-snapshot version on branch master..."

docs/_data/sidebars/pmd_sidebar.yml

@@ -3,7 +3,7 @@
 
 entries:
 - title: sidebar
-  product: PMD Project
+  product: PMD
   version: "!PMD_VERSION!"
   folders:
 
@@ -79,26 +79,35 @@ entries:
       url: /pmd_rules_java.html
       output: web, pdf
     - title: JavaScript Rules
-      url: /pmd_rules_javascript.html
+      url: /pmd_rules_ecmascript.html
       output: web, pdf
     - title: JSP Rules
       url: /pmd_rules_jsp.html
       output: web, pdf
     - title: PLSQL Rules
       url: /pmd_rules_plsql.html
       output: web, pdf
+    - title: VisualForce Rules
+      url: /pmd_rules_vf.html
+      output: web, pdf
     - title: Apache Velocity Rules
       url: /pmd_rules_vm.html
       output: web, pdf
-    - title: XML and XSL Rules
+    - title: XML Rules
       url: /pmd_rules_xml.html
       output: web, pdf
+    - title: XSL Rules
+      url: /pmd_rules_xsl.html
+      output: web, pdf
   - title: Language Specific Documentation
     output: web, pdf
     folderitems:
     - title: JSP Support
       url: /pmd_languages_jsp.html
       output: web, pdf
+    - title: Java code metrics
+      url: /pmd_java_metrics_index.html
+      output: web, pdf
   - title: Developer Documentation
     output: web, pdf
     folderitems:
@@ -138,9 +147,6 @@ entries:
     - title: Using code metrics in custom rules
       url: /pmd_devdocs_metrics_howto.html
       output: web, pdf
-    - title: Index of code metrics
-      url: /pmd_devdocs_metrics_index.html
-      output: web, pdf
     - title: Making Rulesets
       url: /pmd_devdocs_making_rulesets.html
       output: web, pdf

docs/_includes/sidebar.html

@@ -12,7 +12,7 @@
             {% if folderitem.output contains "web" %}
             {% if folderitem.external_url %}
             <li><a href="{{folderitem.external_url}}" target="_blank">{{folderitem.title}}</a></li>
-            {% elsif page.url == folderitem.url %}
+            {% elsif page.url == folderitem.url or page.sidebaractiveurl == folderitem.url %}
             <li class="active"><a href="{{folderitem.url | remove: "/"}}">{{folderitem.title}}</a></li>
             {% else %}
             <li><a href="{{folderitem.url | remove: "/"}}">{{folderitem.title}}</a></li>

docs/_layouts/page.html

@@ -41,7 +41,12 @@ <h1 class="post-title-main">{{ page.title }}</h1>
 
     {% if site.github_editme_path %}
 
-    <a target="_blank" href="https://github.com/{{site.github_editme_path}}{{page.path}}" class="btn btn-default githubEditButton" role="button"><i class="fa fa-github fa-lg"></i> Edit me</a>
+        {% assign editmepath = page.path %}
+        {% if page.editmepath %}
+            {% assign editmepath = page.editmepath %}
+        {% endif %}
+
+    <a target="_blank" href="https://github.com/{{site.github_editme_path}}{{editmepath}}" class="btn btn-default githubEditButton" role="button"><i class="fa fa-github fa-lg"></i> Edit me</a>
 
     {% endif %}
 

docs/pages/pmd/devdocs/metrics_howto.md

@@ -1,9 +1,9 @@
 ---
 title:  Using code metrics in custom rules
 tags: [customizing]
-summary: "PMD was recently enhanced with the ability to compute code metrics on Java code (the so-called Metrics 
-Framework). This framework provides developers with a straightforward interface to use code metrics in their rules, and 
-to extend the framework with their own custom metrics."
+summary: "PMD was recently enhanced with the ability to compute code metrics on Java and Apex source (the so-called 
+Metrics Framework). This framework provides developers with a straightforward interface to use code metrics in their 
+rules, and to extend the framework with their own custom metrics."
 last_updated: July 20, 2017
 sidebar: pmd_sidebar
 permalink: pmd_devdocs_metrics_howto.html
@@ -13,4 +13,73 @@ folder: pmd/devdocs
 
 ## Using the metrics framework
 
-## Writing custom metrics
+{%include note.html content="Using the metrics framework is for now restricted to Java rules (with plans to support 
+XPath rules later)." %}
+
+To use the metrics framework in a custom rule, the first thing to do would be to enable metrics by adding the 
+`metrics="true"` attribute to your rule's XML element.
+
+{%include note.html content="The following explains how to use the Java metrics framework. The Apex framework 
+differs only by the name of its classes." %}
+
+In PMD's Metrics framework, a metric is an operation that can be carried out on nodes of a certain type and produces 
+a numeric result. In the Java framework, metrics can be computed on operation declaration nodes (constructor and 
+method declaration), and type declaration nodes (class, interface, enum, and annotation declarations). A metric 
+object in the framework can only handle either types or operations, but not both.
+
+The framework provides a library of already implemented metrics. These metrics are referenced by `MetricKey` objects,
+which are listed in two public enums: `JavaClassMetricKey` and `JavaOperationMetricKey`. Metric keys wrap a metric, and
+know which type of node their metric can be computed on. That way, you cannot compute an operation metric on a class 
+declaration node. Metrics that can be computed on operation and type declarations (e.g. NCSS) have one metric key in 
+each enum.
+
+The static façade class `JavaMetrics` is the only entry point to compute metrics in the Java framework. 
+This class provides the method `get` and its overloads. The following sections describes the interface of this class.
+
+### Basic usage
+
+The simplest overloads of `JavaMetrics.get` take two parameters: **a `MetricKey` and a node of the corresponding type.** 
+Say you want to write a rule to report methods that have a high cyclomatic complexity. In your rule's visitor, you 
+can get the value of Cyclo for a method node like so:
+```java
+public Object visit(ASTMethodDeclaration node, Object data) {
+  int cyclo = (int) JavaMetrics.get(JavaOperationMetricKey.CYCLO, node);
+  if (cyclo > 10) {
+    // add violation
+  }
+  return data;
+}
+```
+
+The same goes for class metrics: you select one among `JavaClassMetricKey`'s constants and pass it along with the node
+ to `JavaMetrics.get`.
+
+### Capability checking
+
+Metrics are not necessarily computable on any node of the type they handle. For example, Cyclo cannot be computed on 
+abstract methods. Metric keys provides a `supports(Node)` boolean method to find out if the metric can be computed on
+the specified node. **If the metric cannot be computed on the given node, `JavaMetrics.get` will return `Double.NaN` .** 
+If you're concerned about that, you can condition your call on whether the node is supported or not:
+```java
+public Object visit(ASTMethodDeclaration node, Object data) {
+  if (JavaOperationMetricKey.CYCLO.supports(node)) {
+    int cyclo = (int) JavaMetrics.get(JavaOperationMetricKey.CYCLO, node);
+    if (cyclo > 10) {
+      // add violation
+    }
+    return data;
+  }
+}
+```
+
+### Metric versions
+
+{%include important.html content="Metric versions are about to be revamped into options that can be combined 
+together." %}
+
+
+### Result options
+
+## Writing custom metrics
+
+{%include warning.html content="WIP" %}