Как создать ссылки на ссылку для классов Android в javadoc?

Question

Когда я генерировать Javadoc для моего Android проекта в Eclipse, есть много предупреждений, как

cannot find symbol 
symbol : class TextView 

и

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

Я также попытался

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

в Extra javadoc options (path names with white spaces must be enclosed in quotes) вкладке в Configure Javadoc Arguments (3-й диалог eclipse-> project-> Generate Javadoc).

Но только -link http://java.sun.com/j2se/1.4.2/docs/api/ работает i.e для класса String ссылка http://java.sun.com/j2se/1.4.2/docs/api/java/lang/String.html?is-external=true генерируется. но для android.app.Dialog, никакая ссылка не создается.

Редактировать

Я также попытался выбрать android.jar в Select referenced archives and projects to which links should be generated вкладке в Configure Javadoc arguments for standard doclet (2 диалога eclipse-> project-> Generate Javadoc), , но это создает локальные ссылки на документы в локальном каталоге андроида-SDk , А не онлайновые ссылки на Android, как это делается для Java API.

Answer 1

Javadoc полагается на файл с именем package-list, чтобы определить, какие пакеты Java документированы под данным каталогом. По какой-то причине, такой файл отсутствует для http://d.android.com/reference/, поэтому «наивный» подход с

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

не работает – вы получите предупреждение о том, что пакет-список не может быть получен, и никакие ссылки не сгенерированный в ваши документы. (Примечание: Флажки в этом диалоге 2 затмений просто собрать -link параметры для вас, так что на самом деле не имеет никакого значения)

Однако Javadoc предлагает параметр -linkoffline, чтобы иметь возможность настроить именно для этой ситуации: Вы хотите подключиться к другой документации Javadoc онлайн, но вы не можете получить к ней доступ во время создания собственных документов. Вот как это работает: В то время как -link использует только один параметр (URL-адрес документов JavaDoc, к которому вы хотите привязать), -linkoffline занимает второе место. Это местоположение файла package-list!

Таким образом, ссылки на интернет-справочной документации Android, вы должны не никаких галочек в диалоге 2 затмение, но вместо того, чтобы добавить

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

в Дополнительные параметры Javadoc в 3-м диалоге , Таким образом, вы используете package-list ваших локально установленных Android-документов, но ссылки в вашем сгенерированном Javadoc все равно будут указывать на онлайн-версию.

Надеюсь, это поможет!

Answer 2

Несмотря на то, что я последовал за этим ответом, я обнаружил, что могу заставить его работать, если я экспортировал файл сборки муравьев (javadoc.xml) и вручную добавил файл android.jar в путь к классам. Мой javadoc.XML выглядит следующим образом:

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

Я мог бы генерировать документ, используя ant -f javadoc.xml. Я не мог понять, как правильно это сделать из графического интерфейса Eclipse, поскольку даже выбор правильного архива ссылок не заставил Eclipse добавить android.jar в путь к классам.

Answer 3

После нескольких проб и ошибок (И много предложений, полученных из нескольких поисков в Интернете), мне удалось заставить это работать со специфическим сценарием ANT, который можно запустить в Eclipse с помощью команды «Запустить как -> Ant Build ».

Я сохранил этот файл «javadoc.xml» в каталоге моего проекта параллельно с файлом AndroidManifest.xml.

Вот содержимое файла:

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

Если у вас есть проблемы с пути к SDK вы можете вручную создать package-list файл (или скопировать один под $ANDROID_HOME/docs/reference/package-list) к вашему проекту.

Чтобы использовать относительный путь, вы не должны использовать префикс file:/. Если вы поместите файл в sub-directory/package-list аргумент будет -linkoffline http://d.android.com/reference sub-directory

Answer 5

Благодаря @Henning

Вот что мне нужно в муравей build.xml файл:

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

Answer 6

Для тех из нас, смея достаточно, чтобы иметь переключился на постоянно развивающуюся Android-студию & Gradle, одна из вещей, которая на самом деле работает и упрощает работу, относится к местоположению списка пакетов либо локально, либо в Интернете. Например, следующий код из Julian генерирует файлы 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' 
} 

Но это привело предупреждение во время сборки, так как пакет-список не доступен (если он вообще был) на

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

Сначала я подумал, может быть избыточная ссылка/ссылка была проблема, но пакет-лист был также недоступен в

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

Итак, после прочтения обсуждения по этой теме, что одна линия может быть изменен, чтобы обратиться к местной справочной директории в SDK:

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

Он находит пакет-лист локально и не отображает предупреждающее сообщение больше.