欢迎光临
专注android技术,聚焦行业精粹,我们一直在努力

Android javadoc 生成 API 文档

 

1、背景

在开发一个通用组件后,我们经常需要提供一份该组件的接口文档给到使用者。这份接口文档需要包括:类描述,接口方法描述,参数描述等。这当然有很多的处理方式,例如你可以维护一份word文档,但这意味着每次接口更新,你都要维护这样的word文档,容易遗漏。

javadoc就为我们解决了这个问题,我们可以看到Android的developer网站就做的非常不错。javadoc有个最大的好处是它和代码绑定在一起,代码改它也会随之改变,保证文档的正确性和及时性。且javadoc自带的样式排版也非常美观,其它程序员也很轻松的阅读和理解。

2、生成步骤

  1. Android studio 里面点击Tools > Generate JavaDoc…

2、在“Specify Generate JavaDoc Scope”对话框中设置doc的范围。大多数情况下我们只有一些像外观类这样的对外的java文件需要生成javadoc,其它都混淆。所以我们可以在对话框中的sope中选择“Custom scope”

3. 如果需要自定义生成范围,可以选择“Custom scope”并点击旁边的“…”更多按钮,如下图所示添加一个本地的scope

 

 

4. 点击“Local”选择一个本地工程下面的某个目录作为范围,并生成该目录下面的java文件的javadoc

5. 最终设置输出目录,生成的级别等参数后,点击“OK”即可。输出结果如下:

 

6. 以后就可以在输出目录下点击index.html访问自己的javadoc了,也可以将这些doc打包给到接入方,又或者部署到服务器上对外开放访问。总之非常方便。

 

注意:我们可能遇到这样的生成错误——“错误: 编码GBK的不可映射字符”,这是因为编码的问题。你可以在上面第2步的对话框中的“Other command line arguments”中添加下面这样的命令

3、文档注释

通过上面的步骤你已经可以生成你想要范围的java文件的javadoc了。但这时你可能发现doc里面一些文案排版不够美观,没关系。我们可以用一些类似html的标签来优化一下我们注释里面的排版。以下介绍常用的一些标签。

@块标记
常用的块标记有:
1) @author 作者:用于包、类、接口,可以有多个;
2) @version 版本号:用于包、类、接口;
3) @since JDKx.x:支持的 JDK 版本,用于包、类、接口、构造器、方法、属性;
4) @param 参数名 描述:形参的说明,用于构造器、方法;
5) @return 描述:函数返回值的说明,用于方法;
6) @throws 异常类名 描述:可能会抛出的异常说明,用于构造器、方法;
7) @exception 异常类名 描述:同@throws标记;
8) @deprecated 描述:对已过期 API 的描述,用于包、类、接口、构造器、方法、属性;
9) @see 包.类#字段/方法(param…):如果跳转的 url 就是当前类的其他方法/字段,则#之前的可以省略,用于包、类、接口、构造器、方法、属性;
10){@link 包.类#字段/方法(param…)}:同@see标记;
11){@value 包.类#字段}:引用 final 常量的值,用于 final 属性;
12){@code text}:不进行 HTML 解析,表示一个纯文本的代码;
13){@inheritDoc}:从继承的类、接口中继承注释,可以进行拼接,参数、返回值、异常可以在子类中覆盖父类的相关注释。

常用 HTML 标签:
1) <br>:换行;标签
2) <p>:段落标签
3) <blockquote><pre> ... </pre></blockquote>:多行代码块
4) <strong> ... </strong>:粗体强调
5) <em> ... </em>:斜体强调
6) <b> ... </b>:显示粗体
7) <i> ... </i>:显示斜体

赞(1) 打赏
未经允许不得转载:花花鞋 » Android javadoc 生成 API 文档
分享到: 更多 (0)

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

国内精品Android技术社区

联系我们

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏