#1516 [build] doclint error during build

[Andrew Janke]

When trying to build PMD 5.5.1 on OS X 10.11.6 using Homebrew, I'm getting doclint errors that prevent the mvn clean package build step from succeeding.

I had to add an -Xdoclint:none parameter to the POM to get the build to succeed, as shown in the below patch.

Is this expected?

diff --git a/pom.xml b/pom.xml
index 66bd239..8fb40c5 100644
--- a/pom.xml
+++ b/pom.xml
@@ -277,6 +277,7 @@
         <pmd.dogfood.ruleset>${config.basedir}/src/main/resources/rulesets/internal/dogfood.xml</pmd.dogfood.ruleset>
         <checkstyle.configLocation>${config.basedir}/etc/checkstyle-config.xml</checkstyle.configLocation>
         <checkstyle.suppressionsFile>${config.basedir}/etc/checkstyle-suppressions.xml</checkstyle.suppressionsFile>
+        <additionalparam>-Xdoclint:none</additionalparam>
     </properties>

     <build>

[Andreas Dangel]

Thanks for reporting.
I see, you added this patch for homebrew: https://github.com/Homebrew/homebrew-core/commit/5dc3be6983e393aaa95da14461ac00429dafdeb6#pmd.rb

The additonalparam shouldn't be needed. PMD sets this already for the aggregated javadoc generation, as this needs to run with java8 but the current java7 code has many invalid javadoc comments. For the modules, that are already using java8 (pmd-apex, pmd-java8, pmd-ui), such javadoc errors have been already fixed.

Looking at the complete formula, I see, that a toolchains.xml file is created. However, it seems, that for the java7 jdk, still a java8 one is used as jdkhome: line 45 - hence when maven asks for java7, actually java8 is executed.

I don't know how feasible it is, to have multiple java version available for homebrew?
On the other hand, long term goal is of course, to have the javadoc comments fixed in PMD - which is anyway required for switching to java8.
So, I hope, your workaround should be needed only until PMD 5.6... I'll add this ticket to the PMD-5.6.0 Milestone.
What do you think?

[Andrew Janke]

Looking at the complete formula, I see, that a toolchains.xml file is created. However, it seems, that for the java7 jdk, still a java8 one is used as jdkhome: line 45 - hence when maven asks for java7, actually java8 is executed.

Ah, I see: we're basically lying about exactly which Java version lives at that location. Sounds like we should be using /usr/libexec/java_home to find a for-real 1.7 JDK, or omit that stanza if none is installed. And presenting a 1.8 JDK as a 1.7 one is causing the doclint issues, right?

I don't know how feasible it is, to have multiple java version available for homebrew?

Homebrew considers a JDK to be a heavyweight dependency, so we would rather not require that both 1.7 and 1.8 be present. (And in fact, I don't think we have syntax to express a dependency on multiple versions; our dependencies are on a single exact version or exact-version-or-later.) So, having both 1.7 and 1.8 available is not very feasible. But we could detect which version is installed and refine the generated toolchains.xml file based on that, so we're correctly presenting the available toolchains. Would that be sufficient for making a good PMD build?

Thanks for working with me on this!

[Andreas Dangel]

The doclint issues have been fixed and the "-Xdoclint:none" workaround is removed.
Note: This is only done in the master branch, so you'll need to keep the workaround until PMD 5.6.0 is released.

I think, using the most recent available JDK, is the right way. Currently, at least java7 is required, for some features (like Apex) java8 is required. Ideally, you would let PMD build with java8 if available.