257

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

blahdiblah
  • 33,069
  • 21
  • 98
  • 152
Sergii Pechenizkyi
  • 22,227
  • 7
  • 60
  • 71
  • 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 Jun 02 '12 at 19:24
  • 2
    There is an issue for this bug http://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 Jun 09 '12 at 06:12

12 Answers12

400

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

tir38
  • 9,810
  • 10
  • 64
  • 107
JJD
  • 50,076
  • 60
  • 203
  • 339
  • Thanks, very informative. Would it be working the same if sources or javadoc are in folder or zip not a single jar ? – Sergii Pechenizkyi Jul 20 '12 at 19:11
  • I guess so. The .jar archive is a .zip compression format to my knowledge. And if you unpack the javadoc archive you can also link to that folder as VinceFR suggested. – JJD Jul 20 '12 at 22:05
  • 7
    Ahhh, it was the closing and reopening of the Eclipse project which was required for me. (I had refreshed and cleaned several times with no luck before that.) – Steve Haley Jul 26 '12 at 13:12
  • 4
    Thanks @JJD that worked great. I just had to restart Eclipse before it started working. – javajavajavajavajava Aug 16 '12 at 14:25
  • Doesn't work for me. I'm using ADT-20, latest Eclipse, etc. I've tried with the jars in both the libs directory and in its parent. I've reopened, refreshed and cleaned the project and restarted Eclipse. Also I get the error "The JAR of this class file belongs to container 'Android Dependencies' which does not allow modifications to source attachments on its entries" and in Java Build Path->Libraries it says "Source attachment/Javadoc location: (None) - non modifyable". – Timmmm Aug 19 '12 at 13:31
  • @Timmmm Please try with the GSON library once, to checkout if your problem has something to do with the library you like to work with. Should take you a minute or less. – JJD Aug 19 '12 at 19:03
  • worked for me with ADT 20.0.3. My source folder is a zip file and it contains index.html and it works. – vallllll Oct 17 '12 at 15:29
  • @JJD Tried again with SLf4J and worked. Maybe it was an issue with robotium jars. – Mister Smith Oct 25 '12 at 07:39
  • @MisterSmith I confirm that *rototium* does not show the JavaDoc in the panel when you move the jars in `libs` folder. Their [test project](http://robotium.googlecode.com/files/ExampleTestProject_v3.5.1.zip) however works out of the box (shows the JavaDoc but uses another project structure). I recommend you **open a new question** on *robotium* in particular. I guess it has sth. to do with how the ..javadoc.jar has been generated. You could try to compile it yourself from the sources. As I can see there are some files missing which are included in the javadoc.jar of gson. – JJD Oct 25 '12 at 19:53
  • @JJD So it wasn't just me. Ok. Thanks for checking that. – Mister Smith Oct 26 '12 at 07:20
  • 26
    **Note:** You *really* **should** put the Javadoc and source JARs into a subdirectory, e.g. "./libs/docs", otherwise these JARs will be bundled into your APK! Also, you won't be able to include Javadoc for multiple libraries, as building the APK will fail when it finds duplicate HTML files. – Christopher Orr Nov 28 '12 at 12:03
  • @Christopher Thank you for this advice. Do you know if it is *enough* to move them to a subdirectory of "libs/" or do I need to move them to a top level folder to guarantee that they will not be bundled? – JJD Nov 28 '12 at 12:08
  • Yeah, I put them into a subdirectory and that worked fine since the build system only looks at "libs" and not its subdirectories. I tried previously with a top-level directory (i.e. src=../foo/my-src.jar) but that wasn't accepted by Eclipse. – Christopher Orr Nov 28 '12 at 21:57
  • Looks like a great explanation but not working for twitter4j which has to be placed in the libs directory to avoid otherwise unexplained crashes on object instantiation. Anyone got this to work with twitter4j? – MindSpiker Dec 18 '12 at 08:03
  • 1
    I've incorporated @Christopher's advice into the answer since not following that advice results in a bad project setup. – Nick Feb 23 '13 at 15:09
  • 5
    Is it possible to refer to a remote javadoc from the .properties file? Like so: doc=http://community.versant.com/documentation/reference/db4o-8.0/java/api/ – Matthias Feb 23 '13 at 19:27
  • 1
    It didn't work for me, using ADT 21.1. Why doesn't google provide an automatic way for using the javadocs, as they've done with the libs folder itself? – android developer Mar 30 '13 at 22:17
  • @androiddeveloper I updated my answer and tested the setup with the latest version, ADT 21.1. As you can tell from the screenshot everything works fine for me. Please provide more details on what fails on your project. – JJD Mar 31 '13 at 22:31
  • I've tried it on this library: https://code.google.com/p/roottools/wiki/Usage . maybe it's the library's fault? – android developer Mar 31 '13 at 23:10
  • @androiddeveloper You should add the name of the library you are having problems with in the first statement. - I tried it myself for more then 1 hour also by renaming, generating JavaDoc from source but could **not** get it running. Sry. Please open a separate question for [RootTools](https://code.google.com/p/roottools/) and link it here. – JJD Apr 01 '13 at 18:34
  • @JJD i am sorry. i didn't know it was the library's fault. i thought it should work for any library. – android developer Apr 01 '13 at 19:47
  • @androiddeveloper No worries. Open a question and link it here. – JJD Apr 02 '13 at 12:34
  • @JJD no i don't need it. javadocs are cool, but i can handle code without it, especially if there are just a few functions. too bad that android framework can't handle the whole thing automatically (or at least in a nicer manual way). – android developer Apr 02 '13 at 15:47
  • 9
    Apparently this doesn't work if you are only going to link the Javadoc and not the source code, I had to extract the Javadoc jar with 7zip to a folder in My Documents, then have the properties file point to the folder with the Javadoc index.html directly like so doc=C:\\Users\\johny\\workspacenewfb\\robotium-solo-4.0-javadoc – mbwasi Apr 06 '13 at 16:46
  • @mbwasi Are you talking about the RootTools library I've tried to use? If so, thanks. – android developer Apr 08 '13 at 22:32
  • I tried this with GSON, it does not seem to work anymore with JAR files, only extracting the JAR to a directory has worked for me. – silverjam Apr 12 '13 at 00:11
  • @silverjam Please state the library you use and feel free to open a **new question** with the specific library. Please link the question here. I will then reply in hour question. – JJD Apr 12 '13 at 08:34
  • 3
    Note: if you use a file name of gson-2.2.2.properties instead of gson-2.2.2.**jar**.properties it won't work (obviously). – Jason Axelson May 28 '13 at 07:30
  • 2
    Refreshing the project didn't help for me. But restarting Eclipse did. – Leo Landau Jul 02 '13 at 21:49
  • I had similar problems to the ones above. In my case, it worked until I built and ran the project. Then the java docs would no longer show up when hovering even though they were still shown as attached in the "Libraries" tab of the Java Build Path. I found a method that consistently works by abandoning the use of the "lib" folder altogether. I have documented this method below to help others avoid hours of frustration. – Danny Remington - OMS Jul 17 '13 at 16:59
  • @DannyRemington-OMS Can you please add which libraries you tried to integrate so I can try to help? Is it *crmlite* as shown in your post? I know there are libraries such as *robotium* as *MisterSmith* wrote which do not behave as expected. – JJD Jul 18 '13 at 10:06
  • 1
    How do you make it work on the android admob sdk? I've followed the steps written here and it didn't work. how do i use relative path too ? – android developer Oct 30 '13 at 06:19
  • @MisterSmith unpacking the robotium jar and altering the .properties file worked for me – barry Nov 07 '13 at 13:27
  • 2
    @JJD, excellent summary. Much appreciated. However, this does not seem to work for Javadoc web URLs. For example, I can't do `doc=http://www.joda.org/joda-time/apidocs/` in my `joda-time-2.3.jar.properties` file. Am I correct on this, or is there something I'm missing? It sure would be nice to simply link to the public Javadoc hosted online rather than maintain the separate `-sources.jar` and `-javadoc.jar` JARs for each library. I've tried setting the Javadoc location path URL under "Java Build Path > Libraries > Javadoc location" for the JAR in question, but it doesn't work. Thanks! – The Awnry Bear Feb 11 '14 at 06:29
  • @TheAwnryBear Hm, remote documentation. This interesting. I have not tried this. I would appreciate if you **open a new question** for exactly this issue so it receives more visibility than here in the comment. I am happy to link the question up there then. – JJD Feb 14 '14 at 11:40
  • @JJD, thanks for the quick response. I'll open a new question later today (Friday the 14th). Thanks again. :) – The Awnry Bear Feb 14 '14 at 12:10
  • @TheAwnryBear Please put the link to your question here if you opened one. – JJD Feb 25 '14 at 16:33
  • 2
    I find it terrible that ADT as of R22 still can't work with libraries if you don't have the source code by default. Having to jump through these hoops is absolutely ridiculous. – Mgamerz Mar 05 '14 at 18:37
  • 2
    Adding javadoc alone didn't work for me (for GSON library, specifically). I had to add the sources.jar too! – Bojan Radivojevic May 16 '14 at 13:17
  • 1
    Damn i missed ".jar" in the NAME of the properties file. "...jar.properties" – M. Usman Khan May 28 '14 at 10:11
  • Javadoc only support HTML files, does NOT support archive. >>> [Google Code Reference](https://code.google.com/p/android/issues/detail?id=27490#c21) : Source attachement: to work with the new dependency system, we need to put the source attachement outside of the eclipse config. Next to any jar files in libs/ simply put a .properties file (foo.jar -> foo.jar.properties). This properties file currently support two properties: src: relative or absolute path to the source folder (or archive). doc: relative or absolute path to the javadoc. – situee Oct 13 '14 at 05:08
  • 1
    do not miss prefix ".jar" when make "properties" file. Not "jarName.properties", but "jarName.jar.properties" – iroiroys Nov 24 '17 at 03:36
25

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
farid_z
  • 1,673
  • 21
  • 11
17

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!

VinceFR
  • 2,551
  • 1
  • 21
  • 27
10

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

JJD
  • 50,076
  • 60
  • 203
  • 339
Danny Remington - OMS
  • 5,244
  • 4
  • 32
  • 21
5

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.

Carlos Sobrinho
  • 135
  • 8
4

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.

Javide
  • 2,477
  • 5
  • 45
  • 61
  • This is by far the easiest and most direct method to attach a javadoc and/or src to a library. Thanks! As an added note, neither the javadoc nor the src are required to be in the Referenced Library. – k_rollo Sep 26 '15 at 04:13
3

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

Mark Gittoes
  • 131
  • 3
  • Didn't work for me. Where do you have the jar file kept in your project? I have mine in the libs folder. – Daniel Ryan Apr 04 '12 at 00:26
  • Finally someone gave an instruction that actually worked! Thanky you very much. None of the forementioned methods including the ".properties" file did any good for me, but this adding the library as an external JAR in the dialog screen did the job. – AlxDroidDev Jul 04 '16 at 19:04
1

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.

Gábor
  • 9,466
  • 3
  • 65
  • 79
1

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

krinklesaurus
  • 1,606
  • 3
  • 21
  • 38
1

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.

Casey Murray
  • 1,582
  • 17
  • 21
0

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!

EWit
  • 1,954
  • 13
  • 22
  • 19
akshay
  • 1
0

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

Gama11
  • 31,714
  • 9
  • 78
  • 100
Antonio Martin
  • 361
  • 3
  • 12