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

Question

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?

You need to attach the javadocs when building your artifact in its Pom.xml. Then they go together in the maven repository b — Thorbjørn Ravn Andersen, May 21 '23 at 16:30
When I build my project, it produces two JAR files. How do I attach the javadocs JAR to the artifact? — Francis Rubio, May 21 '23 at 16:57

xerx593 · Answer 1 · 2023-05-21T18:10:26.067

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".

I don't think this would work in this situation because the library I need Javadocs for is a local one that I made in another project. I just tried this and it indicates that my library has not been resolved. — Francis Rubio, May 21 '23 at 17:07
what means "local one" ? (is it released to a maven repo? or `system`!? ;( — xerx593, May 21 '23 at 17:09
for long term: you have to "mavenize" this! (install/deploy it (with sources and javadoc!) to local/repo), to quickly work in ide..: see screenshot ;) — xerx593, May 21 '23 at 17:32
Thank you for pointing me in the right direction! I ended up "mavenizing" my library by deploying the library + javadoc to a local repository (.m2 directory), and adding that path into my `pom.xml` repositories. I also removed the `system`. Javadocs are working now even after Maven reloads. — Francis Rubio, May 21 '23 at 17:40

Thilo Schwarz · Accepted Answer · 2023-05-22T06:44:56.707

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>

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

2 Answers2