[MJAVADOC-329] Allow generation of empty Javadoc JARs

[jira-importer]

Vincent Massol opened MJAVADOC-329 and commented

Here's my use case:

• I want to be able to deploy my artifacts to Maven Central. There's a requirement that a javadoc jar exists for the arifact to deploy
• However I have some maven modules of type packaging = jar that have java files but these files are located in an "internal" package (internal api that we don't expose to end users since it's not part of our public API contract) which we exclude from the javadoc generation

The problem is that the javadoc plugin doesn't generate any JAR if there are no java files matching (even if I have other files such as a package.html file in my src/main/javadoc/* directories).

I'd like it to be possible to generate an "empty" javadoc JAR containing only a package.html file for example.

Thanks a lot

---

Affects: 2.8

Remote Links:

• GitHub Pull Request #331
  
• GitHub Pull Request #65
  

2 votes, 6 watchers

[jira-importer]

Michael Osipov commented

Have you considered using the assembly plugin for that?

[jira-importer]

John Robert Fallows commented

The requirement for deployment to Maven Central via Sonatype is to always produce a javadoc JAR, empty or otherwise. If a project initially has only internal (excluded) packages and therefore no javadoc JAR, the deployment fails.

One of the most straightforward solutions would be to include a boolean flag on the javadoc plugin configuration such as "generateIfEmpty" and default to false for backwards compatibility. Projects deploying to Maven Central could simply configure "generateIfEmpty" to true.

The proposal to use assembly plugin could be made to work but creates churn on the POM as the project evolves to include sources that require actual javadoc.

The problem is further exacerbated when dealing with more than one project (not aggregated). Configuring the javadoc plugin once in the parent POM for all such projects would be ideal.

[jira-importer]

Vincent Massol commented

Workaround:

<!-- Because of http://jira.codehaus.org/browse/MJAVADOC-329 we need to find a workaround to create a Javadoc
     JAR to satisfy the Maven Central Repository requirements. We do this by creating an apidocs/ dir in the
     target directory.
     Note that even though this "hack" is only needed for java projects having all their sources in the
     internal packages we put it here in the top level POM to not have to duplicate it at lots of places. -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-antrun-plugin</artifactId>
  <executions>
    <execution>
      <!-- The Javadoc JAR plugin runs in the package phase so we need a phase before that -->
      <phase>generate-resources</phase>
      <configuration>
        <target>
          <mkdir dir="${project.build.directory}/apidocs" />
        </target>
      </configuration>
      <goals>
        <goal>run</goal>
      </goals>
    </execution>
  </executions>
</plugin>

[jira-importer]

Michael Osipov commented

What about adding a packing-info.java in the root package which is not internal, the output won't be empty then?

[jira-importer]

Robert Scholte commented

I agree with Michael Osipov : putting a package-info file is the least you should do to inform the users of that jar. An empty javadoc jar will only raise more questions.

[jira-importer]

Vincent Massol commented

Hi Robert Scholte. Small note that I never said I wanted a fully empty javadoc, I even mentioned this:

The problem is that the javadoc plugin doesn't generate any JAR if there are no java files matching (even if I have other files such as a package.html file in my src/main/javadoc/* directories).
I'd like it to be possible to generate an "empty" javadoc JAR containing only a package.html file for example.

It's a bit weird that the javadoc plugin wouldn't support having only a package.html file and that this issue is closed a won't fix. But the doc says that package-info.java is now preferred over package.html so I guess it's acceptable. See https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#packagecomment :

The package-info.java file can contain the package declaration, package annotations, package comments, and Javadoc tags. This file is preferred.

[jira-importer]

Robert Scholte commented

I can reopen and work on an IT to ensure that a jar with only package-info.java if that helps.

[jira-importer]

Vincent Massol commented

Robert Scholte As you wish, I don't really need it on my side. Since we're using the workaround I mentioned in a comment above, producing empty javadoc jars. I agree that it would be nicer to have package info but we've been doing this for over 7 years and nobody complained to far. We now have thousands of packages and it would be quite a large task to document them all at package level. We have developer doc but on the wiki of the project.

Thanks for asking.

[jira-importer]

Robert Scholte commented

Interesting, I can't figure out how to instruct the javadoc tool. It keeps failing with

Constructing Javadoc information...
javadoc: error - No public or protected classes found to document.
1 error

[jira-importer]

Robert Scholte commented

https://bugs.java.com/bugdatabase/view_bug.do?bug_id=4492654 Marked as Won't Fix

[jira-importer]

Martin Desruisseaux commented

Well, bug 4492654 is marked "won't fix" because… already fixed (according the evaluation).

About this issue, not sure it would make any difference, but have you tried with javac option -Xpkginfo:always? (Javadoc uses the generated .class files, but I'm not sure what it is doing with them).

[jira-importer]

Robert Scholte commented

It seems javadoc requires at least 1 class to be documented... Can't find a flag to suppress that.

[jira-importer]

John Robert Fallows commented

Pull request implementing generateIfEmpty for javadoc:jar goal.

#65

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-antrun-plugin</artifactId>
  <executions>
    <execution>
      <phase>package</phase>
      <configuration>
        <target>
          <mkdir dir="${project.build.directory}/apidocs" />
        </target>
      </configuration>
      <goals>
        <goal>run</goal>
      </goals>
    </execution>
  </executions>
</plugin>
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.2.0</version>
  <configuration>
    <sourceFileExcludes>
      <exclude>**/internal/**/*.java</exclude>
    </sourceFileExcludes>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

where no non-internal classes exist, therefore no public Javadoc is required, yet Maven Central requires inclusion of a Javadoc JAR during deployment.

This now simplifies to

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.2.1</version>
  <configuration>
    <sourceFileExcludes>
      <exclude>**/internal/**/*.java</exclude>
    </sourceFileExcludes>
    <generateIfEmpty>true</generateIfEmpty>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>