Maven dependency with javadocs

Question

3 Questions:

Below are two maven dependencies for JUnit. I have been scouring the interwebs for hours and cannot seem to determine if the second one is Javadoc + code or only Javadoc. Do I need one or both? Further, what is the most effecient way to include Javadocs in a project for development yet not in the production build? (I would prefer not to manually download javadocs for every dependency on every machine.)

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.11</version>
</dependency>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.11</version>
  <classifier>javadoc</classifier>
</dependency>

EDIT: Questions:

What is the difference between these dependencies?
Do I need both of them to be able to use the dependency & have Javadoc on hand?
What is best practice for including Javadocs for development?

This should help (If I get one of your question right): http://stackoverflow.com/questions/5780758/maven-always-download-sources-and-javadocs — Andreas Dolk, Jul 05 '13 at 21:23
@Andreas_D I looked at that one before. I did the recommended add yet got a little lost at this step: "Then make sure the activeProfiles includes the new profile." — AnthonyW, Jul 05 '13 at 21:33
It should be sufficient to copy the code from the answer there to your `~/.m2/settings.xml` file. You may have to add the profile element to you profiles (if there are already some defined) — Andreas Dolk, Jul 05 '13 at 22:36

score 13 · Answer 1 · edited Jun 20 '20 at 09:12

Generally Javadocs are not primarily used as dependency. Because these are neither required at compile nor runtime. It’s just to help the developer while developing or debugging.

Assuming using the java IDE Eclipse we can use the java docs as referenced. Following are the approaches we can associate the javadocs/sources with the respective jars.

1. If it’s non-maven project : Download the javadocs jar or zipped file, whatever available and placed it in some directory. Right click on the application project in the IDE Eclipse, click Properties and choose Java Build Path then select tab Libraries under the Java Build Path. Now expand the jar you want to link with java docs/source. Select the Javadoc location link and click on Edit button, a new window appears where we need to choose the javadocs jar path. Click OK and we have linked the javadoc/source with the respective jars.

2. If it’s a maven project

If we are using the Maven project then go to jar files under the Maven dependency under the project in Project Explorer view as shown below. Now right click on the jar file you want to add the Javadoc/source,  choose Maven then click on Javadoc or Source you want to link with the project. Now IDE will automatically download the required javadoc/source and will link it with the respective jar in the project.

You can verify this by right click on the project in the IDE and click on Java Build Path and select the Libraries tab under the Java Build Path and then expand the desired jar, here when you click the Edit button you will see the linked path of the Javadoc/Source with the respective jar as shown below in the image.

3. If it’s Maven project and we are setting the default behaviour:

Eclipse will aquatically download the javadoc/source along with the main required jar at the starting. By default setting instruction to Maven to download the Javadoc/sources for all the jars linked in the project.

Click Windows – preferences – select Maven and click the checkbox Download Artifact Javadoc as shown below

Now click on apply and save it and now when you create new Maven project , by default the Javadocs will get downloaded and linked with all the dependent jars in the project.
You can verify by right click on the project and Properties and under Java Build path can see the javadocs are linked with all the jars as shown below.

If your project is Maven project then It’s always best to use 2nd approach because by using this approach the IDE and Maven, takes care of downloading the correct version of the Javadoc/source and linked it with the relative jar as well.

Approach 3rd is bit costly because the javadoc/sources will be downloaded forall the dependent jars, may be you are not interested for javadocs/sources for all the dependent jars.

score 9 · Accepted Answer · answered Jul 05 '13 at 22:36

9

Generally speaking, your IDE will handle the resolution of javadoc for you in a maven project. This is assuming your IDE understands maven - e.g. netbeans, intellij or eclipse w/ m2e.

The second artifact is only the javadocs. The first artifact is the code. There's almost never a good reason to include the javadoc artifact as a dependency.

answered Jul 05 '13 at 22:36

John Ament

11,595
1
36
45

3

THANK YOU!! That second paragraph alone answers about a half-dozen open questions on SO. – AnthonyW Jul 05 '13 at 22:59
1

I am using Eclipse w/ m2e. Once I tie in a dependency, JUnit in this example, is there somewhere I can right click and tell it to pull the docs? – AnthonyW Jul 05 '13 at 23:01
5

If you ctrl+click in to one of the methods in JUnit, you should see it pull in the code. Then when you mouse over the methods (e.g. `org.junit.Assert.assertNotNull`), you should start seeing the javadocs populate if they didn't already start. – John Ament Jul 06 '13 at 17:35
In Netbeans you need to go into dependencies (in the project view), right-click a jar and select "Download Javadoc." – Sean Anderson Jul 17 '22 at 15:37

score 2 · Answer 3 · answered Sep 21 '15 at 13:35

I stumbled upon this problem when I created a maven project in eclipse and neither javadoc nor source of my dependencies where attached to my project, and I wondered which dependency to add.

What helped me was adding

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-source-plugin</artifactId>
        </plugin>

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
        </plugin>
    </plugins>
</build>

to my pom.xml. That way, you only have to use the first dependency, and maven/eclipse take care of downloading the second (which is, as pointed out in the other answer, only the javadoc).

Maven dependency with javadocs

3 Answers3