¿Cómo generar enlaces a la referencia de las clases de Android en javadoc?

Question

Cuando genero javadoc para mi proyecto Android en Eclipse, hay un montón de advertencias como

cannot find symbol 
symbol : class TextView 

y

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

También probé

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

en Extra javadoc options (path names with white spaces must be enclosed in quotes) pestaña en Configure Javadoc Arguments (3er diálogo de eclipse-> proyecto-> Generar Javadoc).

Pero solo -link http://java.sun.com/j2se/1.4.2/docs/api/ funciona, es decir, para la clase String se genera el enlace http://java.sun.com/j2se/1.4.2/docs/api/java/lang/String.html?is-external=true. pero para android.app.Dialog, no se genera ningún enlace.

Editar

También probé la selección de android.jar en Select referenced archives and projects to which links should be generated pestaña en Configure Javadoc arguments for standard doclet (segundo diálogo de en Eclipse> Proyecto-> Generar Javadoc), pero esto crea enlaces a documentos locales en el directorio android-sdk locales , NO las referencias en línea de Android como lo hace para las API de Java.

Answer 1

Javadoc se basa en un archivo llamado package-list para determinar qué paquetes Java están documentados debajo de un directorio determinado. Por alguna razón, tal archivo es falta para http://d.android.com/reference/, por lo tanto, el enfoque de "ingenua" con

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

no funciona – se obtiene una advertencia de que la lista de paquete no se pudo recuperar y hay enlaces son generado en sus documentos. (Nota: Las casillas de verificación en ese cuadro de diálogo segunda Eclipse acaba de montar -link parámetros para usted, por lo que en realidad no hace ninguna diferencia)

Sin embargo, Javadoc ofrece el parámetro -linkoffline para poder ajustar con precisión esta situación: Desea vincular a otra documentación de Javadoc en línea, pero no puede acceder a ella en el momento de generar sus propios documentos. Así es como funciona: Mientras que -link toma solo un parámetro (la URL de los documentos JavaDoc que desea vincular), -linkoffline toma una segunda. ¡Esa es la ubicación del archivo package-list!

lo tanto, para enlazar con la documentación de referencia de Android en línea, usted debe no seleccione ninguna casilla de verificación en el cuadro de diálogo segundo eclipse, pero en lugar de añadir

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

en los opciones Javadoc extra en el tercio de diálogo . De esta forma, utiliza el package-list de sus documentos Android instalados localmente, pero los enlaces en su Javadoc generado aún seguirán apuntando a la versión en línea.

Espero que ayude!

Answer 2

Aunque seguí para responder arriba, encontré que solo podía hacer que funcionara si exportaba un archivo de compilación ant (javadoc.xml) y añadía manualmente el archivo android.jar al classpath. Mi javadoc.XML es así:

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

entonces podría generar el documento usando ant -f javadoc.xml. No pude encontrar una manera de hacerlo correctamente desde la GUI de Eclipse, ya que incluso seleccionar el archivo de referencia correcto no causaba que Eclipse añadiera android.jar al classpath.

Answer 3

Después de un poco de prueba y error (y un montón de sugerencias recopiladas de múltiples búsquedas web), pude hacer que funcione con un script ANT específico, que se puede ejecutar en Eclipse mediante "Ejecutar como -> Ant Build ".

Guarde este archivo, "javadoc.xml", en el directorio de mi proyecto, en paralelo con el archivo AndroidManifest.xml.

Aquí es el contenido del archivo:

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

Si tiene problemas con la ruta de acceso al SDK puede crear manualmente un archivo package-list (o copiar el que está bajo $ANDROID_HOME/docs/reference/package-list) para su proyecto.

Para utilizar una ruta relativa no debe usar el prefijo file:/. Si coloca el archivo en sub-directory/package-list el argumento sería -linkoffline http://d.android.com/reference sub-directory

Answer 5

Gracias @Henning

Aquí está lo que necesitaba en el archivo build.xml hormiga:

<link offline="true" href="http://d.android.com/reference" packagelistLoc="${android.home}/docs/reference"/> 

Answer 6

Para aquellos de nosotros lo suficientemente atrevido a tener cambiado a Android Studio &, siempre en evolución, Gradle, una de las cosas que realmente funciona y facilita un poco las cosas es referirse a una ubicación de lista de paquetes localmente o en la web. Por ejemplo, el siguiente código de Julian genera archivos Javadoc:

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

Pero esto dio lugar a una advertencia durante la construcción debido a que la lista de paquetes ya no está disponible (si es que alguna vez lo fue) en

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

al principio pensé que tal vez la referencia redundante/de referencia era el problema, pero la lista de paquete también estaba disponible en

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

Así que, después de leer la discusión en este hilo, que una línea se puede cambiar para hacer referencia al directorio local de referencia dentro del SDK:

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

encuentra la lista de paquetes a nivel local y no muestra el mensaje de advertencia más.