Java io操作新api javadoc api

转载

编程小天才 2023-12-08 19:47:45

文章标签 Java io操作新api javad Android java 文章分类 Java 后端开发

DOC API文档生成过程

1 工具使用及设置
2 javadoc工具
3 如何快速打开SDK中类及方法文档
4. 方法及类注释
5. gradle中javadoc配置
6. 参考

1 工具使用及设置

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

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

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

Java io操作新api javadoc api_Android

工具设置：

Java io操作新api javadoc api_javad_02

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

Java io操作新api javadoc api_javad_03

Java io操作新api javadoc api_Java io操作新api_04

2 javadoc工具

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

Java io操作新api javadoc api_Java io操作新api_05

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

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

Java io操作新api javadoc api_Java io操作新api_06

4. 方法及类注释

方法1

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

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

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

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

// 单行注释

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

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

注意开头是两个*。

方法2

自定义注释模版步骤：

File->Setting->Editor->Live Templates。
点击+，创建一个Template Group，输入group名字。
选中你刚刚创建的group，创建Live Template。
填写Abbreviation,我这里填的是cmt,也即你这个注释的快捷方式，你敲cmt加回车，模板就出来了。

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

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

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

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

Java io操作新api javadoc api_java_07

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的工具链。