How to add a Javadoc JAR file to a Maven project in IntelliJ IDEA?

I am making a local Java utility library and building it into a JAR file. I am also building a JAR file for the Javadocs.

These are the JAR files generated by Maven:

Now, I am trying to use the Javadocs JAR file with IntelliJ IDEA by importing it in File > Project Structure, and it works. I get hints and documentation for code references in my IDE. But as soon as I reload my Maven project, the Javadocs are gone and I have to manually add it back.

I am also getting this warning from IntelliJ everytime I add the Javadoc JAR file back.

What is the proper way of adding a Javadoc JAR file into a Maven project?

Pure Maven (good IDEs should recognize these):

mvn dependency:resolve -Dclassifier=javadoc

Ref: https://maven.apache.org/plugins/maven-dependency-plugin/resolve-mojo.html

Notes: It's rather unusual (unless explicitly ordered) to "package" (dependency) javadocs with the main artifact... In maven, "we" rather maintain (own!) artifacts for "main"/sources/and javadocs (See: https://maven.apache.org/repository/guide-central-repository-upload.html)

As mentioned, good IDEs should be capable of processing the "local repository" for javadoc (and source) artifacts of undrlying dependencies.

To "download sources" use:

mvn dependency:sources

Ref: https://maven.apache.org/plugins/maven-dependency-plugin/sources-mojo.html

When your (remote) Repository does not comply with "central requirements" (has no "source" and "javadoc" artifacts attached),
also to eliminate (any) <scope>system</scope> dependency, I would strongly recommend (to "mavenize" the dependencies and) install/deploy sources and javadocs artifacts for this:

• locally with: mvn install:install ...
• to a "repo": mvn deploy:...

For "mavenize" refer to:

• locally: https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html
• for "deployments": https://maven.apache.org/guides/mini/guide-3rd-party-jars-remote.html

Specifically for sources and javadocs artifacts (once you have/generate these):

• deploy: https://maven.apache.org/plugins/maven-deploy-plugin/examples/deploying-sources-javadoc.html
• accordingly with "install-file"

The "pure IDE" way, would be to link to the (external!) sources/javadocs (in file system/zip/jar archive):
... See screenshot:

• com.example:my-dep:0.0.1-SNAPSHOT is my (fake) system scoped dependency.

• After "applying" changes and confirming the warn dialog (iml vs pom, re-import...), IntelliJ should recoginze javadocs and sources.

• According to the warning our "modifications" get lost in case of a "maven re-import".

There is a more general maven-style way and should be preferred over the "IDE way". You can use a local "fake" repository inside your project. Add the jar files to your repo. The maven call depends on the type of the jar.

The jar:

mvn deploy:deploy-file \
  -DgroupId=org.example \
  -DartifactId=mylib\
  -Dversion=1.1 \
  -Dfile=/path/to/mylib-1.1.jar \
  -Dpackaging=jar \
  -Durl=file://path/to/your-project/fake-repo

The sources:

mvn deploy:deploy-file \
  -DgroupId=org.example \
  -DartifactId=mylib\
  -Dversion=1.1 \
  -Dfile=/path/to/mylib-1.1-sources.jar \
  -Dpackaging=jar \
  -Durl=file://path/to/your-project/fake-repo \
  -Dclassifier=sources

The javadoc:

mvn deploy:deploy-file \
  -DgroupId=org.example \
  -DartifactId=mylib\
  -Dversion=1.1 \
  -Dfile=/path/to/mylib-1.1-javadoc.jar \
  -Dpackaging=jar \
  -Durl=file://path/to/your-project/fake-repo \
  -Dclassifier=javadoc

The next step is adding the repo and the dependency to your pom:

<repositories>
  <repository>
    <id>fake-repo</id>
    <name>Just a fake repository.</name>
    <url>file://${project.basedir}/fake-repo</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>org.example</groupId>
    <artifactId>mylib</artifactId>
    <version>1.1</version>
  </dependency>
</dependencies>