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?

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>