这里的“stubs”是通过运行javadoc工具生成的框架API存根。
在大多数情况下,当我们谈论Android中的存根文件时,我们指的是由aidl工具生成的java文件。例如参见如何在android中生成存根? - 堆栈溢出
特别是,Android 构建系统包含一个名为droiddoc.mk
可用于生成文档、java API 存根和 API xml 文件,这实际上调用了 javadoc。
droiddoc.mk
在下面build/core
. In build/core/config.mk
有一个变量名为BUILD_DROIDDOC
以便更容易地包括droiddoc.mk
.
看着那(这droiddoc.mk
,它调用 javadoc:
javadoc \
\@$(PRIVATE_SRC_LIST_FILE) \
-J-Xmx1280m \
$(PRIVATE_PROFILING_OPTIONS) \
-quiet \
-doclet com.google.doclava.Doclava \
-docletpath $(PRIVATE_DOCLETPATH) \
-templatedir $(PRIVATE_CUSTOM_TEMPLATE_DIR) \
$(PRIVATE_DROIDDOC_HTML_DIR) \
$(addprefix -bootclasspath ,$(PRIVATE_BOOTCLASSPATH)) \
$(addprefix -classpath ,$(PRIVATE_CLASSPATH)) \
-sourcepath $(PRIVATE_SOURCE_PATH)$(addprefix :,$(PRIVATE_CLASSPATH)) \
-d $(PRIVATE_OUT_DIR) \
$(PRIVATE_CURRENT_BUILD) $(PRIVATE_CURRENT_TIME) \
$(PRIVATE_DROIDDOC_OPTIONS) \
&& touch -f $@
存根什么也没有吧?别担心,注意有一个PRIVATE_DROIDDOC_OPTIONS
变量,以及
PRIVATE_DROIDDOC_OPTIONS := $(LOCAL_DROIDDOC_OPTIONS)
AOSP 中的许多 Android.mk 文件,例如framework/base/Android.mk
,包含include $(BUILD_DROIDDOC)
生成文档。在framework/base/Android.mk
,有一段代码:
LOCAL_DROIDDOC_OPTIONS:=\
$(framework_docs_LOCAL_DROIDDOC_OPTIONS) \
-stubs $(TARGET_OUT_COMMON_INTERMEDIATES)/JAVA_LIBRARIES/android_stubs_current_intermediates/src \
-api $(INTERNAL_PLATFORM_API_FILE) \
-nodocs
LOCAL_DROIDDOC_CUSTOM_TEMPLATE_DIR:=build/tools/droiddoc/templates-sdk
LOCAL_UNINSTALLABLE_MODULE := true
include $(BUILD_DROIDDOC)
The LOCAL_DROIDDOC_OPTIONS
包含一个-stubs
选项。最终会放入 droiddoc.mk 使用的 javadoc 命令中。
但是,我们可能会注意到 javadoc 不包含任何选项,例如-stubs
。关键是您可以使用 doclet 自定义 Javadoc 工具输出的内容和格式。 Javadoc 工具有一个默认的“内置”doclet,称为标准 doclet,它生成 HTML 格式的 API 文档。您可以修改标准 doclet 或对其进行子类化,或者编写自己的 doclet 来生成 HTML、XML、MIF、RTF 或您想要的任何输出格式。
我们可以使用-doclet
指定我们定制的 doclet 的选项。 droiddoc.mk 中的 javadoc 命令使用-doclet com.google.doclava.Doclava
。该 doclet 接收-stubs
option.
看看下面的 Doclava 实现external/doclava/src/com/google/doclava/Doclava.java
else if (a[0].equals("-stubs")) {
stubsDir = a[1];
} else if (a[0].equals("-stubpackages")) {
stubPackages = new HashSet<String>();
for (String pkg : a[1].split(":")) {
stubPackages.add(pkg);
}
}
它接收 -stubs 选项。以下是它处理 StubsDir 的方式。
// Stubs
if (stubsDir != null || apiFile != null || proguardFile != null) {
Stubs.writeStubsAndApi(stubsDir, apiFile, proguardFile, stubPackages);
}
并追踪执行情况Stubs.writeStubsAndApi
,您可以看到为什么存根文件中的内容是这样的。
您甚至可以编写自己的 java 文件并生成存根,就像下面的测试用例一样build/tools/droiddoc/test
.