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

Ответ 1

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

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

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

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

Итак, чтобы ссылаться на онлайн-справочную документацию по Android, вы должны не выбирать любые флажки во втором диалоге затмения, а вместо этого добавлять

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

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

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

Ответ 2

После небольшого количества проб и ошибок (и много предложений, полученных из нескольких поисков в Интернете), мне удалось заставить это работать с определенным ANT script, который можно запустить в Eclipse с помощью команды "Запустить как", > ANT Сборка ".

Я сохранил этот файл "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>

Ответ 3

Несмотря на то, что я ответил на этот вопрос, я обнаружил, что могу заставить его работать, если я экспортировал файл сборки ant (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 в путь к классам.

Ответ 4

Спасибо @Henning

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

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

Ответ 5

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

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

Ответ 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");

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