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

256
votes

New version of ADT r17 plugin for Eclipse added feature to automatically setup JAR dependencies. Any .jar files in the /libs folder are added to the build configuration now. Unfortunately Android Dependencies classpath container is non modifiable.

Non modifiable android dependencies classpath

How can i attach javadoc and sources to the automatically inserted .jar (from /libs folder)?

12
androideclipseadtjavadoc
I don't think your question was answered. Mark's accepted answer gives exactly what you asked NOT to be the solution. How can we attach javadoc and sources via the auto-libs (not via manual jars)? – pjv
There is an issue for this bug code.google.com/p/android/issues/detail?id=27490#c21 . Comment 21 says that attach sources/javadoc will be possible in ADT r20 with a standard java .properties file (foo.jar -> foo.jar.properties) which allows you edit relative or absolute path to the source folder (or archive) and/or relative or absolute path to the javadoc. – Sergii Pechenizkyi

12 Answers

400
votes

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:

JavaDoc view in Eclipse

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

Eclipse test project screenshot

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.

GoogleAdMobAds Android library Eclipse project

25
votes

On windows you have to escape the backslash for references to doc and src paths in the properties file. Example, for android-support-v4.jar the properties file content is something like:

doc=C:\\Program Files (x86)\\Android\\android-sdk\\extras\\android\\support\\v4\\docs
src=C:\\Program Files (x86)\\Android\\android-sdk\\extras\\android\\support\\v4\\src
17
votes

An answer come from http://code.google.com/p/android/issues/detail?id=27490#c21

In your libs folder, you must have:

doc(folder)
    foo_doc(folder)
        index.html
        ...
        ...
foo.jar
foo.jar.properties

And in your foo.jar.properties, just put doc=./doc/foo_doc

Maybe you will have to refresh your project, to clean it, to close it and to reopen it.

It works for me!

10
votes

I tried all of the above and none of them worked for me. I figured out a method that will always work. Basically, the culprit is the way that the ADT treats the "libs" folder so I quit using the "libs" folder. Instead I created a "libraries" folder and used it.

You can do the following and it will always work - even if the ADT should change how it changes how it deals with the "libs" folder in the future:

  1. Create a "libraries" folder.
  2. Create a sub-folder under it for each library.
  3. Put all of the files for each library in the appropriate folder (java jar file, source jar file, javadoc jar file, etc).
  4. Add the java jar file for each project in the "Libraries" tab for the Java Build Path by clicking on the Add Jars... button to add the jar from the library sub-folder in the "libraries" folder.
  5. Attach the source/javadocs to each project by opening the project in the "Libraries" tab, selecting the desired item, and clicking on the Edit... button to add the source/javadocs from the library sub-folder in the "libraries" folder.
  6. Check the checkbox for each project in the "Order and Export" tab for the Java Build Path.
  7. After verifying that all libraries have been moved delete the "libs" folder.

By following the above procedure your project will have folders that look like this:

enter image description here

Your Java Build Path will look something like this:

enter image description here

In Order and Export the libraries are ticked:

enter image description here

5
votes

For now, move the library you want Javadoc to lib. Them add that library to the Build Path and add the Javadoc.

Check this comment in the android issues.

4
votes

On ADT 22 I could not access Javadoc for both commons-io-2.4.jar and android-support-v4.jar

This is the way I fixed it:

  1. Precondition: both libraries are listed under "Referenced Libraries".

  2. Right click on commons-io-2.4.jar and select Properties. This window appears:

enter image description here

commons-io-2.4.jar is bundled with commons-io-2.4-javadoc.jar, so I specified the Javadoc in archive External file path.

I did the same thing for the support library: right click on android-support-v4.jar and select Properties. This screen appears:

enter image description here

This time I specied the path to the source directory.

3
votes

The library reference to commons-io-2.0.1.jar was broken when I upgraded to SDK Tools and ADT revision 17.

To resolve the problem I used Project -> Properties - > Java Build Path and I selected the Libraries tab. I deleted any reference to commons-io-2.0.1.jar and then used Add Jar to re-add commons-io-2.0.1.jar to the project. Then I click the ‘>’ arrow next to the library name to expand the library reference and I used the edit buttons to set the Source attachment and the Javadoc location.

Sorry I can't post an image as I don't have enough rep (please...).

1
votes

Seems to be a moving target but, after having collected bits and pieces from many places (including answers to this very question that helped but failed to describe all necessary details, or maybe the system had changed slightly in the meantime), this seems to be the solution, at least as of now (August 28, 2013).

  • Open up a folder for your javadocs somewhere not inside your project.
  • Put your javadocs there unzipped, each into its own folder.
  • Inside your lib folder, add an xxx.jar.properties file for each lib you want to associate a javadoc with.
  • In that properties file, refer to the folder you unzipped the appropriate javadoc into (on Windows, escape the backslashes):

doc=d:\\Android\\javadoc\\libGoogleAnalyticsServices

  • Close and reopen your project in Eclipse (refreshing is not enough). You should now see the tooltips when you hover over the appropriate classes.

Failing to observe any of these steps (not unzipping the javadoc, referencing a file instead of a folder, etc) seems to break it.

1
votes

I know this question is rather old, but when I was facing the same problem yesterday and the solution posted above was way too annoying for me, I found out that one can easily add a source path definition to the .classpath file of the project. Eclipse will then adapt it and you're able to browse through the source.

classpath entry before:

<classpathentry kind="lib" path="[PATH_TO_MY_JAR]"/>

After adding the path to the source

<classpathentry kind="lib" path="[PATH_TO_MY_JAR]" sourcepath="[PATH_TO_MY_SOURCE_JAR]"/>

Hope this helps

0
votes

just update the ADT plugin. That worked for me!!

  1. Start Eclipse, then select Help > Install New Software.
  2. Click Add, in the top-right corner.
  3. In the Add Repository dialog that appears, enter "ADT Plugin" for the Name and the following URL for the Location: https://dl-ssl.google.com/android/eclipse/ Note: The Android Developer Tools update site requires a secure connection. Make sure the update site URL you enter starts with HTTPS.
  4. Click OK. In the Available Software dialog, select the checkbox next to Developer Tools and click Next.
  5. In the next window, you'll see a list of the tools to be downloaded. Click Next.
  6. Read and accept the license agreements, then click Finish.
  7. If you get a security warning saying that the authenticity or validity of the software can't be established, click OK.
  8. When the installation completes, restart Eclipse

Hope that helps!

0
votes

For any given jar, if you would like to see the Javadoc help on the tooltip while coding, do the following: Right click your project > Properties > Java Build Path > Libraries Tab. Click the arrow next to your jar to expand.

Source attachment should point to the location of the actual jar (probably right in your java folder).

Javadoc location: You have two choices here: URL and archive. If your javadocs for this jar are in the form of a folder containing an index.html file at the first level, choose 'Javadoc URL' and point to that folder. If your javadocs are in a jar, choose 'Javadoc in archive' and point to the jar. Don't forget to restart your workspace/close and reopen your project to update the tooltip with the Javadoc info.

I hope this helps give a simple answer for what I believe should be a very simple task.

0
votes

My solution:

Download an eclipse plugin called: "Java Source Attacher Feature".

Later, select a jar and attach the source code using this plugin. Click in the jar file to select it, right buttom on the mouse, and then select "attach java source".

When you have the source code you have automatically the javadoc.

Now you can use F2 over the classes to view the asociated javadoc.

Enjoy