如何在javadoc中生成到Android类参考的链接?

28

在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/

配置 Javadoc 参数 的第三个对话框中的 额外的 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,没有链接被生成。

编辑

我也尝试在 配置标准 Doclet 的 Javadoc 参数 的第二个对话框中的 选择要生成链接的引用存档和项目 选项卡中选择 android.jar,但这会创建指向本地 android-sdk 目录中文档的本地链接,而不是像 Java API 一样链接到在线 Android 引用。

7个回答

42

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中的链接仍将指向在线版本。

希望能帮到您!


谢谢 Henning,它起作用了!!我真的花了很多时间来解决这个问题,但没有成功。非常感谢。 - Vasu
1
我似乎无法在Mac OS X上正确获取第二个参数中的文件路径。 - user370382
谢谢你的建议,但是我无法让它对我起作用。具体来说,我正在Windows上使用Eclipse。我的javadoc包括像"{@link android.widget.Toast}"这样的引用。当我选择"生成Javadoc..."时,在第二个屏幕上我没有勾选任何内容,并且我包括额外的Javadoc选项-linkoffline http://d.android.com/reference file:"\C:\Program Files (x86)\Android\android-sdk-windows\docs\"。Javadoc被成功生成,但它包含了android.widget.Toast,而我期望的是一个链接。有什么建议吗?谢谢。 - Ellen Spertus
1
  1. 您需要docs目录下面的reference目录的路径。
  2. 在Windows上不要使用带有括号的路径名--这会经常导致问题(特别是在Java中)。
  3. 使用正斜杠(也适用于Java)。
  4. 引号可能需要包括file:,因为它是URI的一部分。 摘要: 将Android SDK移动(或符号链接)到C:\Android,然后使用-linkoffline http://d.android.com/reference "file:/C:/Android/android-sdk-windows/docs/reference"
- Henning
难道不应该是 file://C:/... 吗? - Michael Mrozek
它对我没用。我也在Windows上使用Eclipse,并添加了 -linkoffline http://d.android.com/reference file:/D:/Programme/Android/android-sdk/docs/reference (包列表文件在那里)。 我没有检查其他任何内容,但我收到了很多“错误:包android.os不存在 导入android.os.Bundle;”的错误有什么建议是问题所在? - Radon8472

4
到目前为止(2020年8月),谷歌已经在其Android开发者文档中发布了一个package-list。因此,简单地链接到https://developer.android.com/reference/https://d.android.com/reference/将起作用(我刚试过并取得成功)。
小问题:如果您打开生成的Javadoc并尝试跟随指向Android类(或其中一个标准Java类,这也将链接到Android文档)的链接,并且您处于框架模式下,则您的浏览器可能拒绝跟随该链接,因为Android站点不允许嵌入到另一个页面中。然后Firefox会给您提供在新标签页中打开目标文档的替代选择。

1
如果您想以同样的方式使用AndroidX,也可以添加-linkoffline https://developer.android.com/reference/ https://developer.android.com/reference/androidx/ - Steve
http:// 没有日志输出,无法工作,https:// 可以正常工作。 - nift4

2

经过一些试错(以及从多次网络搜索中获得的许多建议),我成功地使用了一个特定的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>

1

虽然我按照这里的最佳答案操作,但我发现只有在导出一个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添加到类路径中。


1
如果您使用Eclipse Indigo,在导出Javadoc的第四个框中,在“额外的Javadoc选项”框中,您可以将additionalparam属性的值粘贴到其中。 - user942821

1

感谢 @Henning

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

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

那对我不起作用。我使用了这个答案https://dev59.com/l3E85IYBdhLWcg3wXCIv#5193647 - Muzikant

0

对于那些敢于转向不断发展的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'
}

但是这导致构建过程中出现警告,因为 package-list 不再可用(如果曾经可用)于

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

起初我以为多余的引用/参考可能是问题所在,但 package-list 也无法使用。
options.links("http://developer.android.com/reference/");

所以,在阅读了这个帖子的讨论后,那一行代码可以被修改为引用SDK内部的本地参考目录:

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

它会在本地查找软件包列表,不再显示警告信息。

0
如果您在SDK路径上遇到问题,可以手动创建一个package-list文件(或复制$ANDROID_HOME/docs/reference/package-list下的文件)到您的项目中。
要使用相对路径,不应使用file:/前缀。如果您将文件放在子目录/package-list中,则参数应为-linkoffline http://d.android.com/reference 子目录

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接