28

When I generate javadoc for my Android project in Eclipse, there are lots of warnings like

cannot find symbol
symbol  : class TextView

and 

warning - Tag @see: reference not found: android.app.Dialog

I also tried 

-link http://developer.android.com/reference/
-link http://java.sun.com/j2se/1.4.2/docs/api/

in Extra javadoc options (path names with white spaces must be enclosed in quotes) tab in Configure Javadoc Arguments (3rd dialog of eclipse->project->Generate Javadoc).

But only -link http://java.sun.com/j2se/1.4.2/docs/api/ is working i.e for String class link http://java.sun.com/j2se/1.4.2/docs/api/java/lang/String.html?is-external=true is generated. but for android.app.Dialog , no link is generated.

Edit

I also tried selecting android.jar in Select referenced archives and projects to which links should be generated tab in Configure Javadoc arguments for standard doclet (2nd dialog of eclipse->project->Generate Javadoc), but this creates local links to docs in local android-sdk directory, NOT the online Android references like it does for Java APIs.

Bill the Lizard
  • 398,270
  • 210
  • 566
  • 880
Vasu
  • 4,862
  • 8
  • 42
  • 48

7 Answers7

42

Javadoc relies on a file called package-list to determine what Java packages are documented below a given directory. For some reason, such a file is missing for http://d.android.com/reference/, therefore the "naive" approach with

-link http://d.android.com/reference/

doesn't work – you get a warning that the package-list could not be retrieved and no links are generated into your docs. (Note: The checkboxes in that 2nd eclipse dialog just assemble -link parameters for you, so that doesn't really make any difference)

However, Javadoc offers the -linkoffline parameter to be able to adjust for precisely this situation: You want to link to some other Javadoc documentation online, but you cannot access it at the time of generating your own docs. Here's how it works: While -link takes only one parameter (the URL of the JavaDoc docs you want to link to), -linkoffline takes a second one. That one is the location of the package-list file!

So, to link to the online Android reference documentation, you should not select any checkboxes in the 2nd eclipse dialog, but instead add

-linkoffline http://d.android.com/reference file:/C:/pathtoyour/android-sdk-windows/docs/reference

in the Extra Javadoc options in the 3rd dialog. That way you use the package-list of your locally installed Android docs, but the links in your generated Javadoc will still point to the online version anyway.

Hope it helps!

Henning
  • 11,496
  • 5
  • 27
  • 25
  • Thanks Henning, It worked !! I really had spent a lot of time to solve this but not succeeded. Thanks a lot. – Vasu May 13 '10 at 05:21
  • 1
    I can't seem to get the filepath in the second argument correct on Mac OS X. – idolize Jul 23 '10 at 19:57
  • thanks for the tip, but I wasn't able to get it to work for me. Specifically, I'm using Eclipse on Windows. My javadoc includes references like "{@link android.widget.Toast}". When I choose "Generate Javadoc...", I do not check anything on the second screen, and I include the extra Javadoc option `-linkoffline http://d.android.com/reference file:"\C:\Program Files (x86)\Android\android-sdk-windows\docs\"`. Javadoc is generated without error, but it includes `android.widget.Toast` where I expected a link. Any suggestions? Thanks. – Ellen Spertus Mar 01 '11 at 06:10
  • 1
    **1.** You need the path to the `reference` directory _below_ the `docs` directory. **2.** Don't use path names with parentheses on Windows -- it breaks all the time (especially with Java). **3.** Use forward slashes (also with Java). **4.** The quotation marks probably need to include the `file:` as well, as it's part of the URI. **Summary:** Move (or symlink) your Android SDK to `C:\Android`, then use `-linkoffline http://d.android.com/reference "file:/C:/Android/android-sdk-windows/docs/reference"` – Henning Mar 01 '11 at 12:56
  • Should it not be `file://C:/...`? – Michael Mrozek Jul 28 '15 at 19:44
  • It worked not for me. I m using Eclipse on Windows too, and I have added `-linkoffline http://d.android.com/reference file:/D:/Programme/Android/android-sdk/docs/reference` (package-list file is there). I did not check anything else, but I get lots of 'error: package android.os does not exist import android.os.Bundle;' errors Any suggestions whats the problem ? – Radon8472 Nov 02 '16 at 13:55
4

By now (August 2020), Google has published a package-list on its Android developer documentation. Hence, simply linking to https://developer.android.com/reference/ or https://d.android.com/reference/ will work (just tried this with success).

Minor glitch: if you open the generated Javadoc and try to follow a link to an Android class (or one of the standard Java classes, which will also link to the Android documentation) and you are in frame mode, your browser might refuse to follow the link, as the Android site does not allow embedding in another page. Firefox then gives you the alternative of opening the target document in a new tab.

user149408
  • 5,385
  • 4
  • 33
  • 69
  • 1
    If you want AndroidX in the same way, you can also add `-linkoffline https://developer.android.com/reference/ https://developer.android.com/reference/androidx/` – Steve Aug 27 '20 at 16:26
  • http:// doesn't work with no log output, https:// works – nift4 Jan 15 '23 at 10:54
2

After a bit of trial and error (And plenty of suggestions gleaned from multiple web searches), I was able to get this working with a specific ANT script, which can be run in Eclipse by "Run As -> Ant Build".

I saved this file, "javadoc.xml", in the directory of my project, in parallel with the AndroidManifest.xml file.

Here is the content of the file:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project basedir="." default="doc" name="api docs">
<target name="doc" description="my docs">
<javadoc destdir="docs" doctitle="Testing the Title" verbose="on" 
    use="true" 
    classpath="C:\Android\android-sdk_r04-windows\android-sdk-windows\platforms\android-2.1\android.jar;.\libs\admob-sdk-android.jar"
    sourcepath="gen;src"
    linkoffline="http://d.android.com/reference C:\Android\android-sdk_r04-windows\android-sdk-windows\docs\reference"
    stylesheetfile="C:\Android\android-sdk_r04-windows\android-sdk-windows\docs\assets\android-developer-docs.css"
    >
</javadoc>
</target>
</project>
veca
  • 149
  • 1
  • 5
1

Thanks @Henning

Here is what I needed in ant build.xml file:

<link offline="true" href="http://d.android.com/reference" packagelistLoc="${android.home}/docs/reference"/>
Sileria
  • 15,223
  • 4
  • 49
  • 28
1

Although I followed to top answer here, I found I could only get it to work if I exported an ant build file (javadoc.xml), and manually added the android.jar file to the classpath. My javadoc.xml looks like:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project default="javadoc">
    <target name="javadoc">
        <javadoc access="private" additionalparam=" -linkoffline http://developer.android.com/reference file:/opt/android-sdk-linux_x86/docs/reference" author="true" classpath=".:/opt/android-sdk-linux_x86/platforms/android-8/android.jar" destdir="doc" nodeprecated="false" nodeprecatedlist="false" noindex="false" nonavbar="false" notree="false" packagenames="com.example.mypackagename" source="1.5" sourcepath="gen:src" splitindex="true" use="true" version="true"/>
   </target>
</project>

I could then generate the document using ant -f javadoc.xml. I couldn't figure out a way to do it properly from the Eclipse GUI, as even selecting the correct referenced archive did not cause Eclipse to add android.jar to the classpath.

Matt Holgate
  • 533
  • 1
  • 4
  • 10
  • 1
    If you use Eclipse Indigo, in the 4th frame of exporting Javadoc, at box _Extra Javadoc options_, you can paste your value of attribute `additionalparam` into there. –  Mar 01 '12 at 19:21
0

If you have problems with the path to the SDK you can manually create a package-list file (or copy the one under $ANDROID_HOME/docs/reference/package-list) to your project.

To use a relative path you shouldn't use the file:/ prefix. If you put the file in sub-directory/package-list the argument would be -linkoffline http://d.android.com/reference sub-directory

jonasb
  • 1,847
  • 1
  • 17
  • 15
0

For those of us daring enough to have switched over to the ever-evolving Android Studio & Gradle, one of the things that actually works and makes things a little easier is referring to a package-list location either locally or on the web. For example, the following code from Julian generates javadoc files:

task("generate${variant.name.capitalize()}Javadoc", type: Javadoc) {
    title = "Documentation for Android $android.defaultConfig.versionName b$android.defaultConfig.versionCode"
    destinationDir = new File("${project.getProjectDir()}/doc/compiled/", variant.baseName)
    source = variant.javaCompile.source
    ext.androidJar = "${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar"
    classpath = files(variant.javaCompile.classpath.files) + files(ext.androidJar)

    description "Generates Javadoc for $variant.name."

    options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PRIVATE
    options.links("http://docs.oracle.com/javase/7/docs/api/");
    options.links("http://developer.android.com/reference/reference/");
    exclude '**/BuildConfig.java'
    exclude '**/R.java'
}

But this resulted in a warning during the build because the package-list isn't available anymore (if it ever was) at

options.links("http://developer.android.com/reference/reference/");

At first I thought maybe the redundant reference/reference was the issue, but the package-list was also unavailable at

options.links("http://developer.android.com/reference/");

So, after reading the discussion on this thread, that one line can be changed to refer to the local reference directory within the SDK:

options.links("c:\\path-to-sdk-directory\\docs\\reference");

It finds the package-list locally and doesn't display the warning message anymore.

Community
  • 1
  • 1
jkincali
  • 995
  • 1
  • 9
  • 10