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?

Answer 1

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.

Answer 2

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

Answer 3

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.