Javadoc shows 100 warnings and spoils the build log

[mockitoguy]

Let's figure out what to do with 100 warnings from Javadoc that spoil the build log. Can we suppress the warnings while still show Javadoc errors? Alternatively, we could just fix the warnings (not ideal, the warnings don't seem to be useful) + treat warnings as errors so that we will not forget to clean them up in the future.

Steps to reproduce: ./gradlew cleanJavadoc javadoc

Build log contains 100 warnings such as:

/Users/sfaber/mockito/release/src/main/groovy/org/shipkit/internal/notes/format/MultiReleaseNotesFormatter.java:15: warning: no @param for data
    String formatReleaseNotes(Collection<ReleaseNotesData> data);
           ^
/Users/sfaber/mockito/release/src/main/groovy/org/shipkit/internal/notes/format/MultiReleaseNotesFormatter.java:15: warning: no @return
    String formatReleaseNotes(Collection<ReleaseNotesData> data);
           ^
/Users/sfaber/mockito/release/src/main/groovy/org/shipkit/internal/notes/format/ReleaseNotesFormatters.java:22: warning: no @return
    public static MultiReleaseNotesFormatter notableFormatter(String introductionText,
                                             ^

Suggested implementation

See the last comments on this ticket

[janpetryk]

Those warnings are there only if you use Java 8. Further info here: http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

Adding option Xdoclint:none to gradle config (as mentioned in above link) fixes this issue.

But if we suppress those warnings other ones emerge: Users/jpetryk/Projects/shipkit/src/main/groovy/org/shipkit/internal/gradle/util/team/TeamMember.java:9: warning - Tag @link: reference not found: ReleaseConfiguration.Team#getDevelopers() /Users/jpetryk/Projects/shipkit/src/main/groovy/org/shipkit/internal/gradle/util/team/TeamMember.java:9: warning - Tag @link: reference not found: ReleaseConfiguration.Team#getContributors() /Users/jpetryk/Projects/shipkit/src/main/groovy/org/shipkit/internal/gradle/util/team/TeamParser.java:14: warning - Tag @link: reference not found: ReleaseConfiguration.Team#getDevelopers()

Those warnings are actually useful, when fixed, those references create proper anchors in doc file and are clickable in IntelliJ providing easier navigation.

My starting point would be adding

 if (JavaVersion.current().isJava8Compatible()) {
    allprojects {
      tasks.withType(Javadoc) {
        options.addStringOption('Xdoclint:none', '-quiet')
      }
    }

to build.gradle and then go and fix all those remaining link issues.

[wwilk]

@szczepiq We probably can close this one. We lost the ability to fail on errors in javadoc, but this problem is solved and there doesn't seem to be any better solution for this at the moment.

[mockitoguy]

I just ran ./gradlew clean javadoc on my local and I saw 100 warnings. Why do we want to close this ticket? :)

[githubinti]

I fixed it by having classpath entry in the javadoc task. "classpath = sourceSets.main.compileClasspath" So now I am not getting respective warnings and I do not have to hide them from the log.

[mockitoguy]

@githubinti, can you help us an submit a PR? :) We would really appreciate it!

[xeruf]

options does not have an addStringOption for me, so I can't apply the fix...

[xeruf]

Okay I had to write -Xdoclint:none to a file and then call options.optionFiles!!.add("build/tmp/silence.txt") (Kotlin DSL)

[jb08]

fyi could not resolve this issue with

javadoc {
    classpath = sourceSets.main.compileClasspath
}

as suggested above. This led to linker errors:

error: cannot find symbol
import org.shipkit.internal.gradle.util.StringUtil;
                                       ^
  symbol:   class StringUtil
  location: package org.shipkit.internal.gradle.util