CODEWITHSUNDEEP
javamavenmodulejavadocmaven-javadoc-plugin
UrbenLegend
UrbenLegend

Reputation: 351

How do I generate JavaDocs for non-exported packages in a module?

I am currently writing a JavaFX application contained within 1 module and I want to use Javadoc to document all of my code. However, I am noticing that I can't seem to generate Javadocs for packages that have not been exported out of the module in module-info.java. On one hand, that makes sense. Non-exported packages aren't part of the public API. On the other hand, I feel like surely there should be options to enable documentation of internal APIs hidden in non-exported packages, but I've had no success in enabling them.

As this is a Maven project, I've tried the following options with the maven-javadoc-plugin:

  1. <show>private</show>
  2. <additionalOptions>-private</additionalOptions>
  3. <additionalOptions>--show-module-contents all --show-packages all --show-types private</additionalOptions>

None of these work (and I am pretty sure 1 and 2 are the exact same thing). They only show a bit more info on one package that i've exported to another specific module. If I don't have these options, the Modules section of the Javadoc is completely blank with the exception of the module name.

I've done lots of Googling and no one on the Internet seems to bring this issue up. Maybe my Google-Fu is just off? I feel like there's just some silly undocumented flag that I haven't found yet because it can't be the case that you have to export the packages to get Javadocs for them, right?

My project consists of only one module containing 8 packages. None of them need to be fully exported out yet. Only one package containing my JavaFX files needs to be exported to javafx.graphics and that's the only one that gets picked up by Javadoc when I enable <show>private</show>.

Here is a gist of my module and Maven config, if anybody needs it: https://gist.github.com/urbenlegend/753de7bec598fd07d6b5c0b0ef02d1d0

I am invoking Javadoc generation via mvn compile javadoc:javadoc

Anyone here have any tips? Thanks in advance!

Upvotes: 1

Views: 411

Answers (1)

Frank
Frank

Reputation: 23

There is no sense in generating documentation for not exported packages. In an application, only the main entry point is exported. In a library, only the packages with public API are exported. All those packages will be documented. And that are the only ones anyone would ever need a documentation for.

If I am interested in the not exported details of a module, I need to look into the source code anyway. Here the documentation is available, and most development environments have a nice Javadoc view for the code at the cursor.

The only drawback I see is, I have no way of checking the internal documentation for syntax errors. Of course, besides using my development environment or a tool like Checkstyle.

After some experiments, I ended up with this Maven configuration:

<plugin>
  <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.7.0</version>
    <executions>
      <execution>
        <id>create-javadoc-jar</id>
        <goals>
          <goal>jar</goal>
        </goals>
      </execution>
    </executions>
  <configuration>
    <doclint>accessibility,html,syntax,reference</doclint>
    <failOnWarnings>false</failOnWarnings>
    <failOnError>true</failOnError>
    <!-- See https://docs.oracle.com/en/java/javase/22/docs/specs/man/javadoc.html -->
    <additionalOptions>--show-module-contents all --show-packages all --show-types private --show-members private</additionalOptions>
  </configuration>
</plugin>

Now I have the Javadoc for all classes in /target/apidocs/index.html.

Upvotes: 0

Related Questions