Android中Java package的DOC API文档生成过程

1 工具使用及设置

AS中集成了javadoc工具，可以通过简单设置生成doc Api文档。

可以参考stackflow上一篇问答如何通过AS生成Java Doc API
generate-javadoc-error-android-studio

• 工具入口：Tools -> Generate Java Doc…
  

• 工具设置：
  
  选项说明：
  Output directory —— 文档输出目录， 这里设置输出目录为cmcc_common_api
  other command line arguments —— 自定义javadoc命令行参数 这里设置了编码及字符集编码-encoding utf-8 -charset utf-8

• AS最终的命令输出：
  

• 生成文档的目录结构：
  

2 javadoc工具

使用javadoc -help 查看javadoc命令及选项用法。

javadoc命令使用详细细节参考下面的链接

Javadoc 的书写格式和javadoc命令的使用

Javadoc使用详解

Java文档注释用法+JavaDoc的使用详解

3 如何快速打开SDK中类及方法文档

Settings输入Quick Documentation, 可以查看相关快捷键，使用时，光标定位在该类或者方法上，按下相应快捷键即可，如Ctrl+Shift+空格

4. 方法及类注释

方法1

在函数名上面一行输入/**<Enter>，自动会生成如下注释格式：

/**
*这里可以简单介绍函数功能
*@param 
*@param
*@return
*/

注意：
一般的注释格式有如下两种

/* 
*普通多行 
*注释 
*/ 

// 单行注释

而我们要生成API Doc必须是如下形式

/** 
*javadoc 
*要求格式 
*/ 

注意开头是两个*。

方法2

自定义注释模版步骤：

1. File->Setting->Editor->Live Templates。

2. 点击+，创建一个Template Group，输入group名字。

3. 选中你刚刚创建的group，创建Live Template。

4. 填写Abbreviation,我这里填的是cmt,也即你这个注释的快捷方式，你敲cmt加回车，模板就出来了。

Template text是注释的模板，具体你模板要怎么写都可以，我的模板如下：

/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @param [参数1]     [参数1说明]
* @param [参数2]     [参数2说明]
* @return  [返回类型说明]
* @exception/throws [违例类型] [违例说明]
* @see          [类、类#方法、类#成员]
*/

相关信息设置完成后，Apply、OK即可。

AS中模板设置界面如下图，里面有很多有用的模板定义，有兴趣可以实操下，使用时先键入相关模板的Abbreviation，然后按Tab键补全即可。

5. gradle中javadoc配置

生成javadoc的Task如下定义：

task commonApiJavadoc(type: Javadoc) {
    destinationDir = new File('../doc/cmcc_common_api_doc')
    options.encoding "UTF-8"
    options.charSet 'UTF-8'
    options.windowTitle = "cmcc common lib"
    options.memberLevel = JavadocMemberLevel.PROTECTED
    options.linkSource false
    options.author = false
    //source sourceSets.main.java.srcDirs
    source('src/main/java')
    source('build/generated/aidl_source_output_dir/debug/compileDebugAidl/out')
    exclude '**/BuildConfig.java'
    exclude '**/R.java'
    exclude '**/*.aidl'
    failOnError false
}

选项字段含义

Property	描述
classpath	用于解析源代码中的类型引用的类路径
destinationDir	生成文档的目录
excludes	排除文件
executable	用于生成Javadoc的Javadoc可执行文件。如果为null，则使用当前JVM的Javadoc可执行文件。
failOnError	指定在Javadoc生成期间遇到错误时此任务是否失败。
includes	包含模式的集合。
maxMemory	分配给此任务的内存量。
options	Javadoc生成选项。
source	在包含和排除模式应用之后，此任务的来源。忽略不存在的源文件。
title	生成的文档的标题。
toolChain	将用于生成Javadoc的工具链。

6. 参考

Android studio 生成带Kotlin文档的实现方式
https://www.yht7.com/news/32879

浅谈Android Studio导出javadoc文档操作及问题的解决
https://cloud.tencent.com/developer/article/1719778

Android studio中gradle配置打jar包和生成Javadoc文档
https://blog.csdn.net/fight__fight/article/details/78429839

[Android] 配置build.gradle 动态传参
https://www.cnblogs.com/kuliuheng/p/9454280.html

Android Studio生成javadoc之gradle实现
https://blog.csdn.net/ithouse/article/details/79377032?utm_source=blogxgwz9

javadoc 生成自定义的标签
https://www.cnblogs.com/hxn-fight/p/5942604.html