How to generate links to the android Classes' reference in javadoc?

Question

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.

Answer 1

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!

Answer 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>

Answer 3

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.

Answer 4

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"/>

Answer 5

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

Answer 6

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.