如何生成 Android 类的链接？ javadoc中的参考？

Question

当我在 Eclipse 中为 Android 项目生成 javadoc 时，有很多警告，例如

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/

Configure 中的 Extra javadoc options (带空格的路径名必须用引号引起来) 选项卡中 尝试过Javadoc 参数（eclipse->项目->生成 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 为标准 doclet 配置 Javadoc 参数 中的选项卡（eclipse->project->Generate Javadoc 的第二个对话框）， 但这会在本地 android-sdk 目录中创建指向文档的本地链接，而不是像 Java API 那样创建在线 Android 参考。

Answer 1

Javadoc 依赖于一个名为 package-list 的文件来确定给定目录下记录了哪些 Java 包。由于某种原因，http://d.android.com 缺少这样的文件/reference/，因此“天真的”方法

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

不起作用 - 您会收到一条警告，指出无法检索包列表，并且不会生成文档中的链接。 （注意：第二个 Eclipse 对话框中的复选框只是为您组装 -link 参数，因此实际上没有任何区别）

但是，Javadoc 提供了 -linkoffline 参数能够精确地针对这种情况进行调整：您想要链接到其他一些在线 Javadoc 文档，但在生成您自己的文档时无法访问它。它的工作原理如下：-link 仅采用一个参数（您想要链接到的 JavaDoc 文档的 URL），而 -linkoffline 则采用第二个参数。那是 package-list 文件的位置！

因此，要链接到在线 Android 参考文档，您不应在第二个 Eclipse 对话框中选择任何复选框，而应

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

在第三个对话框中添加“额外 Javadoc 选项”。这样，您就可以使用本地安装的 Android 文档的package-list，但生成的 Javadoc 中的链接仍将指向在线版本。

希望有帮助！

Answer 2

截至目前（2020 年 8 月），Google 已在其 Android 开发者文档中发布了package-list。因此，只需链接到 https://developer.android.com/reference/ 或 https://d.android.com/reference/ 可以工作（刚刚尝试成功）。

小故障：如果您打开生成的 Javadoc 并尝试跟踪 Android 类（或标准 Java 类之一，它也将链接到 Android 文档）的链接，并且您处于框架模式，则您的浏览器可能会拒绝跟踪该链接，因为 Android 站点不允许嵌入到其他页面中。然后，Firefox 为您提供了在新选项卡中打开目标文档的选择。

Answer 3

经过一番尝试和错误（以及从多个网络搜索中收集到的大量建议），我能够使用特定的 ANT 脚本来实现此功能，该脚本可以通过“Run As -> Ant Build”在 Eclipse 中运行。

我将此文件“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

尽管我遵循此处的最佳答案，但我发现只有导出 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 GUI 正确执行此操作的方法，因为即使选择正确的引用存档也不会导致 Eclipse 将 android.jar 添加到类路径中。

Answer 5

谢谢@Henning

这是我在 ant build.xml 文件中需要的内容：

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

Answer 6

如果您对 SDK 路径有疑问，可以手动创建一个 package-list 文件（或复制 $ANDROID_HOME/docs/reference/package-list 下的文件）到你的项目。

要使用相对路径，不应使用 file:/ 前缀。如果将文件放入 sub-directory/package-list 中，则参数将为 -linkoffline http://d.android.com/reference sub-directory

Answer 7

对于我们这些有足够勇气转向不断发展的 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");

它在本地查找包列表，并且不再显示警告消息。