Doclint

[stefanbirkner]

Verify Javadoc with doclint. We only use the checks of the groups accessibility and reference, because all other groups report issues.

[Tibor17]

@stefanbirkner
Do you know where my comment has gone?
It was about moving the doclint to maven-compiler-plugin configuration.

[Tibor17]

@stefanbirkner
I am trying to repeat my lost comment, which i am not sure if it will be as good as before.

The point is to configure maven-compiler-plugin instead of maven-javadoc-plugin.
The same feature doclint was introduced in javadoc and javac because the Oracle want the developer to find Javadoc issues in compile time. This makes sense to me and therefore I modified configuration of maven-compiler-plugin.

                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.1</version>
                <configuration>
                    <encoding>${project.build.sourceEncoding}</encoding>
                    <source>${jdkVersion}</source>
                    <target>${jdkVersion}</target>
                    <showWarnings>true</showWarnings>
                    <debug>true</debug>
                    <verbose>true</verbose>
                    <fork>true</fork>
                    <compilerArgs>
                        <args>-Xlint:unchecked</args>
                    </compilerArgs>
                </configuration>

With profiles

        <profile>
            <id>java8</id>
            <activation>
                <jdk>[1.8,)</jdk>
            </activation>
            <build>
                <plugins>
                    <plugin>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <configuration>
                            <compilerArgument>-Xdoclint:html,syntax,accessibility,reference</compilerArgument>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>
        <profile>
            <id>default</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <build>
                <plugins>
                    <plugin>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <configuration>
                            <showDeprecation>true</showDeprecation>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>

You can use -Xdoclint:html,syntax,accessibility,reference, and the number of issues is:
html 23
syntax 9
accessibility 0
reference 2

Since the attribute html reports a lot of issues, I can add it and with it in next pull request.

[stefanbirkner]

@Tibor17 I rebased the branch. Obviously this deleted your comment. I create an issue for the Github team.

[Tibor17]

@stefanbirkner
Pls remove the default plugin groupId org.apache.maven.plugins. Maven will make a guess on groupId in case of default prefixed plugins. See how pom.xml started in early beginning - groupId was avoided as intended.

When I tested my pom.xml, the compiler's config <showDeprecation>true</showDeprecation> was in collision with -Xdoclint and the build faild with errors on deprecated classes with JDK8. I wanted to have only warnings on deprecations. That's the reason why i removed showDeprecation from plugin's config and introduced it in profile "default" activated by default.

Did you test it with JDK8, are there any errors or warnings?

[stefanbirkner]

Thanks for the hint about the group id of default plugins. I change it in the evening.

The project is building without errors on JDK6, JDK7 and JDK8: https://travis-ci.org/stefanbirkner/junit/builds/23911515 Unfortunately Travis doesn't support JDK 5.

[Tibor17]

@stefanbirkner
I am using your branch and launch the build mvn compile javadoc:javadoc -e -X with new jdk.
I can see new arguments in maven-compiler-plugin
[DEBUG] (f) compilerArgs = [-Xlint:unchecked, -Xdoclint:accessibility,reference,syntax]

  <compilerArgs>
    <arg>-Xlint:unchecked</arg>
    <arg>-Xdoclint:accessibility,reference,syntax</arg>
  </compilerArgs>

but the maven-javadoc-plugin has only one parameter:
-Xdoclint:reference
[DEBUG] (f) additionalparam = -Xdoclint:reference

Can you fix it?

[stefanbirkner]

Now javadoc verifies accessibility and reference. Thanks for finding this issue.

[Tibor17]

+1

[stefanbirkner]

This pull request is ready to be merged.

[marcphilipp]

LGTM!

@kcooney Any objections?

[kcooney]

@marcphilipp no objections at all.

@stefanbirkner Thanks for fixing the Javadoc!

[marcphilipp]

Thanks!