CODEWITHSUNDEEP
javadocmaven-javadoc-plugin
Martin Mucha
Martin Mucha

Reputation: 3091

maven-javadoc-plugin generates warning about generating every file. Why/what is it?

Having default maven-javadoc-plugin configuration:

 <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
      <execution>
        <id>attach-javadocs</id>
        <goals>
          <goal>jar</goal>
        </goals>
        <configuration> <!-- add this to disable checking -->
          <doclint>none</doclint>
          <quiet>true</quiet>
        </configuration>
      </execution>
    </executions>
  </plugin>

generates immense warnings, and I have no idea what does it complain about, of even if it's complaining about something.

[WARNING] Javadoc Warnings
[WARNING] Loading source files for package net.homecredit.ofs...
...
[WARNING] Constructing Javadoc information...
[WARNING] Building index for all the packages and classes...
[WARNING] Standard Doclet version 18+37
[WARNING] Building tree for all the packages and classes...
[WARNING] Generating classX.html...
[WARNING] Generating classY.html...
... remaining several thousands warnings.

what is it? How to turn this off? ~I need not to be alarmed, that javadoc is processing stuff in my packages or that it generates javadoc about each class, I'd kinda expect it to do it, and silently. Maybe I have misconfiguration somewhere (where?), but there is no indication of any error and it looks more like trace logging, than actual warnings.

EDIT: removing <doclint>none</doclint> will turn warnings to errors with some actual complaints, like "there you forgot to specify documentation for parameter id" or "this trivial class does not have comment". I tried to search documentation, I saw it once somewhere, but I cannot find it anywhere now. How would look configuration: "do not check anything, I don't care. Just print what was written into javadocs and don't even think about what it is."?

Upvotes: 3

Views: 1447

Answers (2)

m5c
m5c

Reputation: 118

If you just want to omit the warnings about files being generated, the quiet option is what you want. The docs says this is "Shuts off messages so that only the warnings and errors appear [...]". So my guess is even the checkstyle developers did not intend the generation of files to submerge as actual warnings in the maven output.

However, this option does exaclty that: stop raising warnings about behind the scenes activity, but keep up the warnings for problems such as missing documentation in the source code.

So the shortest way to reduce the checkstyle verbosity to the actual warnings and errors you are interested in is:

    <configuration>
        <failOnWarnings>true</failOnWarnings>
        <quiet>true</quiet>
    </configuration>

As for the failOnWarnings, I would argue that it makes sense for a build system to fail on missing javadocs. It is not obvious where to draw a line between trivial and non-trivial functionality, so the safest option would be to just require documentation everywhere. At least this way you ensure every release is properly documented. If this turns out to be too annoying for everyday development you could still set up a non-default maven profile that temporarily deactivates failOnWarnings.

Final comment: I don't have the reputation to comment on you own answer, but I would argue that turning off all errors with <failOnError>false</failOnError>) is rarely a good idea. Usually, when things go wrong, you want to know about it.

Upvotes: 0

Martin Mucha
Martin Mucha

Reputation: 3091

This seems to do the trick.

<configuration>
  <doclint>-html,-syntax,-accessibility,-missing</doclint>
  <failOnError>false</failOnError>
  <quiet>true</quiet>
</configuration>

Upvotes: 4

Related Questions