How to force a javadoc jar even though there is no (public) Javadoc?

Question

I have a Maven multi module project of which some of the sub modules are only for internal use. I don't wish to publish any visible Javadoc for it, as it should not be used directly by 3rd parties. There is not a single public package in them (the package name itself has something like a.b.c.internal.d).

However, to release a jar to Maven Central, OSS Sonatype requires that all library jars have accompanying sources and javadoc jars.

How can I force a javadoc jar to be created with a fixed index or so that tells the purpose of the sub module? A package-info.java comes to mind, but I have no public packages (all packages with the word "internal" in it are ignored).

Answer 1

Don't use the Javadoc tool to produce a jar with non-standard content: use maven-jar-plugin instead to manually create one.

Initial solution taken from https://vzurczak.wordpress.com/2014/08/01/generate-an-empty-javadoc-jar-file/

Here's the final solution I settled on and works generically for all submodules when configured in the parent pom:

Define two profiles:

• one to execute the standard javadoc plugin if no custom javadoc folder is present in the submodule (src/main/javadoc is missing)
• one to execute custom javadoc by means of jar plugin if a custom javadoc folder is present in the submodule (src/main/javadoc is present)

Maven config:

<profiles>
    <profile>
        <id>standard-javadoc</id>
        <activation>
            <file><missing>src/main/javadoc</missing></file>
        </activation>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <executions>
                        <execution>
                            <id>attach-javadocs</id>
                            <goals>
                                <goal>jar</goal>
                            </goals>
                            <phase>package</phase>
                            <configuration>
                                <show>public</show>
                                <failOnError>false</failOnError>
                                <detectOfflineLinks>false</detectOfflineLinks>
                                <doclint>all,-missing</doclint>
                                <nohelp>true</nohelp>
                                <excludePackageNames>*.internal.*,testutil,demo</excludePackageNames>
                                <quiet>true</quiet>
                            </configuration>
                        </execution>
                    </executions>
                    <configuration>
                        <failOnError>false</failOnError>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>

    <profile>
        <id>custom-javadoc</id>
        <activation>
            <file><exists>src/main/javadoc</exists></file>
        </activation>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-jar-plugin</artifactId>
                    <executions>
                        <execution>
                            <phase>package</phase>
                            <goals>
                                <goal>jar</goal>
                            </goals>
                            <configuration>
                                <classifier>javadoc</classifier>
                                <classesDirectory>${project.basedir}/src/main/javadoc</classesDirectory>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

Answer 2

One very ugly work-around I found (and I won't accept this answer), is to simply trigger an error and set fail on error to false. The javadoc-plugin then proceeds with an empty target/apidocs folder and produces an empty submodule-javadoc.jar.

The easiest and simplest way to trigger an error I found is to create an empty package-info.java in the /src root folder. This produces the following build output:

[INFO] --- maven-javadoc-plugin:3.1.1:jar (attach-javadocs) @ my-internal-module --- [INFO] 1 error [ERROR] MavenReportException: Error while generating Javadoc: Exit code: 1 - javadoc: error - No public or protected classes found to document.

Command line was: "C:\Program Files\Java\jdk1.8.0_131\jre..\bin\javadoc.exe" @options @argfile

Refer to the generated Javadoc files in 'D:\workstation\my-parent-project\modules\my-internal-module\target\apidocs' dir.

org.apache.maven.reporting.MavenReportException: Exit code: 1 - javadoc: error - No public or protected classes found to document.

Command line was: "C:\Program Files\Java\jdk1.8.0_131\jre..\bin\javadoc.exe" @options @argfile

Refer to the generated Javadoc files in 'D:\workstation\my-parent-project\modules\my-internal-module\target\apidocs' dir.

    at org.apache.maven.plugins.javadoc.AbstractJavadocMojo.executeJavadocCommandLine(AbstractJavadocMojo.java:5763)
    at org.apache.maven.plugins.javadoc.AbstractJavadocMojo.executeReport(AbstractJavadocMojo.java:2152)
    at org.apache.maven.plugins.javadoc.JavadocJar.doExecute(JavadocJar.java:189)
    at org.apache.maven.plugins.javadoc.AbstractJavadocMojo.execute(AbstractJavadocMojo.java:1911)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:134)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:208)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:154)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:146)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:117)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:81)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build(SingleThreadedBuilder.java:51)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:128)
    at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:309)
    at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:194)
    at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:107)
    at org.apache.maven.cli.MavenCli.execute(MavenCli.java:993)
    at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:345)
    at org.apache.maven.cli.MavenCli.main(MavenCli.java:191)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:498)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:289)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:229)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:415)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:356)

[INFO] Building jar: D:\workstation\my-parent-project\modules\my-internal-module\target\my-internal-module-6.0.0.beta-SNAPSHOT.2-javadoc.jar

With the following plugin configuration:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.1.1</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
            <phase>package</phase>
            <configuration>
                <show>public</show>
                <failOnError>false</failOnError>
                <detectOfflineLinks>false</detectOfflineLinks>
                <doclint>all,-missing</doclint>
                <nohelp>true</nohelp>
                <excludePackageNames>*.internal.*,testutil,demo</excludePackageNames>
                <quiet>true</quiet>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <failOnError>false</failOnError>
    </configuration>
</plugin>

Though that satisfied my primary need (in a very ugly fashion) I would prefer a javadoc with one main custom entry where I explain the purpose of the module.