This is a philosophical or ethical command. Very general. It is something like "fail fast". The reason it came up to my mind is that I wanted to compile and release License3j using Java 8 and JavaDoc refused to compile during release build.

This package is a simple license manager, which has some established user base who require that I keep up with the new versions of BouncyCastle. It itself being a cryptography package should not be outdated and programs are encouraged to use the latest version to avoid security issues. When I executed mvn release:prepare I got many errors:

[ERROR] * <p>
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:132: error: unexpected end tag: </p>
[ERROR] * </p>
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:134: warning: no @param for args
[ERROR] public static void main(String[] args) throws Exception {
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/License3j.java:134: warning: no @throws for java.lang.Exception
[ERROR] public static void main(String[] args) throws Exception {
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/ExtendedLicense.java:73: warning: no @param for expiryDate
[ERROR] public void setExpiry(final Date expiryDate) {
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/License.java:196: warning: no description for @throws
[ERROR] * @throws IOException
[ERROR] ^
[ERROR] /Users/verhasp/github/License3j/src/main/java/com/verhas/licensor/License.java:246: warning: no description for @throws

1. New JavaDoc Wants You DIR

The errors are there because the java doc of License3j is a bit sloppy. Sorry guys, I created the code many years ago and honestly it is not only the java doc that could be improved. As a matter of fact one of the unit tests rely on network and the reachability of GitHub. (Not anymore though, I fixed that.)

The new Java version 8 is very strict regarding to JavaDoc. As you can see on the "Enhancements in Javadoc, Java SE 8" page of ORACLE:

The javadoc tool now has support for checking the content of javadoc comments for issues that could lead to various problems, such as invalid HTML or accessibility issues, in the files that are generated by javadoc. The feature is enabled by default, and can also be controlled by the new -Xdoclint option. For more details, see the output from running "javadoc -X". This feature is also available in javac, although it is not enabled by default there.

To get the release working I had the choice to fix the JavaDoc or to use the configuration

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <additionalparam>-Xdoclint:none</additionalparam>
            </configuration>
        </execution>
    </executions>
</plugin>

in pom.xml. (Source is stackoverflow.)

2. But You Just Won’t DIR

You can easily imagine that you will opt for the second option when you are under time pressure. You fix the issue modifying your pom.xml or other build configuration and forget about it.

But you keep on thinking about why it is the way like that? Why is the new tool strict by default? Is it a good choice? Will it drive people to create better JavaDoc?

(Just for now I assume that the aim of the new behavior was to drive programmers to create better JavaDoc documentation and not simply to annoy us.)

I am a bit suspicious that this alone will be sufficient to improve documentation. Programmers will:

Switch off the lint option.
Delete JavaDoc from the source.
Write some description that Java 8 will accept but is generally meaningless.

or some of them will just write correct java doc. Some of them who were writing it well anyway and will be helped by the new strictness. How many of us? 1% or 2%? The others will just see it as a whip and try to avoid. We would need carrot instead. Hey, bunnies! Where is the carrot?

Comments imported from Wordpress

Martin Grajcar 2015-05-27 19:35:13

The carrot is called markdown javadoc, already scheduled for Java 30.

Nicolai Parlog 2015-05-29 22:01:03

Let me toot my own horn here and put myself into the 1-2% you mention. With LibFX I had about 30 minutes of work to fix the existing docs and now I have that linter on my side. Feels great, you should try it. ;-)

Comments

Please leave your comments using Disqus, or just press one of the happy faces. If for any reason you do not want to leave a comment here, you can still create a Github ticket.