Как генерировать ссылки на ссылки классов Android в Javadoc? - PullRequest
Новая
       13

Как генерировать ссылки на ссылки классов Android в Javadoc?

26 голосов
/ 12 мая 2010

Когда я генерирую 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/ работает, т.е. для класса 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), но это создает локальные ссылки на документы в локальной директории android-sdk, а НЕ на онлайновые ссылки на Android, как это делается для API Java.

Ответы [ 6 ]

42 голосов
/ 13 мая 2010

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, вы должны , а не установить флажки во втором диалоговом окне затмения, а вместо этого добавить

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

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

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

2 голосов
/ 04 марта 2011

После небольшого количества проб и ошибок (и множества предложений, почерпнутых из нескольких поисков в сети), я смог заставить это работать с определенным сценарием ANT, который можно запустить в Eclipse с помощью «Run As -> 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>
1 голос
/ 26 августа 2012

Спасибо @ Хеннинг

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

<link offline="true" href="http://d.android.com/reference" packagelistLoc="${android.home}/docs/reference"/>
1 голос
/ 15 февраля 2011

Несмотря на то, что я следовал за верхним ответом здесь, я обнаружил, что смогу заставить его работать, только если экспортировал файл сборки ant (javadoc.xml), и вручную добавил файл android.jar в classpath. Мой 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 в classpath.

0 голосов
/ 23 апреля 2015

Для тех из нас, кто достаточно смел, чтобы переключиться на постоянно развивающуюся Android Studio & 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");

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

0 голосов
/ 22 мая 2012

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

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

...