How to Attach Javadoc or Sources to Jars in Libs Folder

How to attach javadoc or sources to jars in libs folder?

The best way to answer your question is to summarize the answers from Xavier, plastiv, VinceFR and Christopher.

Step by step guide

In order to link the sources and javadoc to a .jar library that is automatically linked by Eclipse you have to do the following:

1. Place the library .jar file in the libs folder, and the associated source .jar and doc .jar files in separate subfolders such as libs/src and libs/docs. You can use a name other than src and docs if you want, but it's important that the .jar files aren't directly in the libs folder.
2. Create a .properties file in the libs folder with the exact name of the actual library .jar (see example). Make sure you keep the .jar part.
3. Specify the relative paths to the sources and javadoc .jar in the .properties file.
4. Close and re-open the Eclipse project! Optionally, refresh the project by pressing F5.
5. Select an object of the linked library in the source code.
6. Open the Javadoc view in Eclipse to check the documentation (see screenshot).
7. Open the source code declaration (default shortcut: F3) of the selected object.

Example

The example uses the Gson library.

Directory structure of the libs folder:

libs
├── docs
│   └── gson-2.2.2-javadoc.jar
├── gson-2.2.2.jar
├── gson-2.2.2.jar.properties
└── src
    └── gson-2.2.2-sources.jar

Contents of gson-2.2.2.jar.properties

src=src/gson-2.2.2-sources.jar
doc=docs/gson-2.2.2-javadoc.jar

Additional information

You can of course move the javadoc and sources .jar into other folders and specify relative paths. That's up to you. Placing the source and javadoc jars directly into the lib folder is possible but not recommended, as that causes documentation and source code to be included in your application.

Screenshot of the Eclipse JavaDoc panel:

Screenshot of an Eclipse project using Gson with Android 4.2.2.:

---

Referencing unpacked javadocs

In case you want to reference javadocs which are not provided as a packed .jar but simply as files and folders as asked by android developer in the comments do the following:

1. Place the library .jar in the libs/ folder

2. Create a yourlibraryname.jar.properties file (don't forget the .jar) with the following content:

    doc=docs
   

3. Add the javadocs folders to the libs/ folder.

You should come up with the following folder structure:

├── docs
│   ├── allclasses-frame.html
│   ├── allclasses-noframe.html
│   ├── com
│   │   └── google
│   │       └── ads
│   │           ├── Ad.html
│   │           │   ....
│   │           └── package-tree.html
│   │   ...
│   └── stylesheet.css
├── GoogleAdMobAdsSdk-6.4.1.jar
└── GoogleAdMobAdsSdk-6.4.1.jar.properties

Do not forget to close and re-open the Eclipse project as mentioned above!
Here is a screenshot of a working example project referencing the GoogleAdMobAds Android library.

How to attach source or JavaDoc in eclipse for any jar file e.g. JavaFX?

You can configure the Javadocs with downloading jar, basically javadocs will be referred directly from internet.

Complete steps:

1. Open the Build Path page of the project (right click, properties,
   Java build path).
2. Open the Libraries tab.
3. Expand the node of the library in question (JavaFX).
4. Select JavaDoc location and click edit.
5. Enter the location to the file which contains the Javadoc.
   Specifically for the javaFX javadoc enter http://docs.oracle.com/javafx/2.0/api/

for offline javadocs, you can download from : http://www.oracle.com/technetwork/java/javase/documentation/java-se-7-doc-download-435117.html

After clicking Accept License Agreement you can download javafx-2_2_0-apidocs.zip

Adding javadoc to a library included as .jar in NetBeans

On Maven Central, you can have the javadoc jar.

When listing the available files for version 2.1.4 there is a:

twitter4j-core-2.1.4-javadoc.jar

Netbeans should be able to download maven dependencies, including javadoc; at least, IDEA does.

Eclipse how to link a jar containing javadocs/source with its binary?

You can try to CTRL + click on a class that has no source attached (do that in editor). When it shows you some info about the class you'll see the button that guides to attach source dialog. Click it and in dialog that pops up pick the source/javadoc location for your class.

You can also do that from project build path settings you are mentioning: pick libraries tab, expand the library (jar) you want and you'll be offered to pick: source attachment, javadoc attachment, native library location, etc. You just pick whatever you want and edit its current settings.

Or you can do as @JB Nizet said...

Eclipse: Attach source/javadoc to a library via a local property

I believe this would be better achieved through:

• the creation of a linked folder combined with
• the declaration of a linked resource

The linked resource defines a path variable which would be equals to /my/path/to/lib/src

The linked folder would refers to your linked resource

(you can use a variable and not a fixed path, with the "Variable" button)

The variable is actually always local (to one's workspace), and will be modified through the Linked Resources preference screen.

The linked folder can also be... a linked file, thus allowing the reference of an archive through a relative path (relative to the variable).

Then this linked file (here a linked archive) can be associated to your classpathentry in the "source" attribute.

---

The problem with Linked Resources is they are local to the workspace, in the preferences.

You can export the preferences in a [myPrefs.epf] file, and then trim the exported file in order to leave only the lines containing pathvariable:

/instance/org.eclipse.core.resources/pathvariable.MY_DIRECTORY=/my/path/to/lib/src

Anyone can then import this special preference file, which will only affect the "Linked Resources" part.

That solution is not very satisfying, since the .epf preference file can not be loaded automatically in the project.

When I setup a project with a linked resources defining a path, I always leave a big README.txt at the root of my project, in order to incite the user of said project to define that same linked resources with his/her own fixed local path.

Several bugs are in progress to enhance this situation or around the Linked Resources topic.

Especially:

• Exporting a project with linked resources
• Relative paths without variables
• Have linked resources relative to workspace paths
• Would like to use path relative to workspace root

---

DevByStarlight mentions in the comments the project (not very active since Oct. 2011) workspacemechanic.

The Workspace Mechanic automates maintenance of your Eclipse environment by tweaking preferences, adding extension locations, and so on. You can use it to:

• Create a consistent environment among groups as large as the entire company, your local team, or even among your own many workspaces
• Save time setting up new workspaces
• Create tasks that ensure your favorite new preferences are applied to all your current and future workspaces. (This is one of our favorite features!)

The key to the Workspace Mechanic's behavior is the Task.

A task describes a simple test and an action that, when run, changes the environment so the test will subsequently pass.

Tasks can come in many forms: preference files, Java classes, Groovy scripts and Eclipse extensions. You can easily define your own Tasks.

It comes with a collection of scripts:

• workspace-mechanic
• workspacemechanic-settings

---

Related Topics