如何在 javadoc 中生成指向 android 类引用的链接？

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

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.

Answer 3

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

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 6

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 7

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.