android - usar - javadoc eclipse

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

Question

Cuando genero javadoc para mi proyecto de Android en Eclipse, hay muchas advertencias como

cannot find symbol
symbol  : class TextView

y

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

Yo tambien lo intenté

-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) en la pestaña Configure Javadoc Arguments (3er diálogo de eclipse-> proyecto-> Generar Javadoc).

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

Editar

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

Answer 1

Aunque seguí la respuesta principal aquí, descubrí 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 a la ruta de clases. Mi javadoc.xml se ve como:

<?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 hizo que Eclipse agregara android.jar a la ruta de clase.

Answer 2

Después de un poco de prueba y error (y un montón de sugerencias recogidas de varias búsquedas web), pude conseguir que esto funcionara con un script ANT específico, que puede ejecutarse en Eclipse mediante "Ejecutar como -> Ant Build".

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

Aquí está 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 3

Gracias @Henning

Esto es lo que necesitaba en el archivo ant build.xml:

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

Answer 4

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 falta en http://d.android.com/reference/ , por lo tanto, el enfoque "ingenuo" con

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

no funciona: aparece una advertencia que indica que no se pudo recuperar la lista de paquetes y que no se generan enlaces en sus documentos. (Nota: las casillas de verificación en el segundo cuadro de diálogo de eclipse simplemente reúnen los parámetros de -link para usted, por lo que realmente no hay ninguna diferencia)

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

Por lo tanto, para enlazar con la documentación de referencia de Android en línea, no debe seleccionar ninguna casilla de verificación en el cuadro de diálogo del segundo eclipse, sino agregar

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

en las opciones de Javadoc Extra en el 3er diálogo. De esa manera, utiliza la package-list de package-list de sus documentos Android instalados localmente, pero los enlaces en su Javadoc generado seguirán apuntando a la versión en línea de todos modos.

¡Espero eso ayude!

Answer 5

Para aquellos de nosotros que nos hemos atrevido a cambiar a la siempre evolutiva Android Studio & Gradle, una de las cosas que realmente funciona y hace las cosas un poco más fáciles se refiere a la ubicación de una 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 resultó en una advertencia durante la compilación porque la lista de paquetes ya no está disponible (si es que alguna vez lo estuvo) en

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

Al principio pensé que tal vez la referencia / referencia redundante era el problema, pero la lista de paquetes tampoco estaba disponible en

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

Entonces, después de leer la discusión en este hilo, esa única línea se puede cambiar para referirse al directorio de referencia local dentro del SDK:

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

Encuentra la lista de paquetes localmente y ya no muestra el mensaje de advertencia.

Answer 6

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

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