AndroidStudio中为项目生成JavaDoc文档的坑

实践中发现Android Studio在对注释模版的支持特别差劲,有好多小的坑,这里做个记录。


🎃让我们从头说起吧~

我们知道Java中有三种注释语句

//
用于单行注释
/*…*/
用于多行注释,从/开始,到/结束,不能嵌套
/**…*/
则是为支持jdk工具javadoc.exe而特有的注释语句,而这种注释是我们这里最为关注的一种,因为javadoc 工具能从java源文件中读取第三种注释,并能识别注释中用@标识的一些特殊变量,制作成Html格式的类说明文档。

javadoc不但能对一个 java源文件生成注释文档,而且能对目录和包生成交叉链接的html格式的类说明文档,类似于我们经常查阅的JavaAPI文档,AndroidAPI文档一样,我们的项目也需要这样一份文档来方便开发人员查阅使用,而这些的前提便是我们的注释需要按照一定格式来编写。

还有需要注意的是javadoc可以将java文件中的文档注释生成为html文件并显示出来,那么既然这样我们如果在注释中使用html的标签会不会生效的,答案是肯定的,<pr/>换行符 <b></b>段落 <li>列表等都是很常用的标签,但是这些是需要我们自己视情况添加的,运用得当的话生成的文档自然更加美观,可读性更高。(还有代码逼格+30%的增幅效果)


🎃下面我们回到主题,Javadoc这么好用,我们该按什么样的格式编写适合Javadoc的注释呢,AndroidStudio为我们准备了相关辅助功能(虽然暂时或许还不是很完善)

🍃首先是类,接口这些文件的头文件(就是会出现在import下方,文件名上方的注释),我们需要使用什么功能怎么编写呢

IDE提供了一个File Header的设置功能,File - Setting - Editor - File and Code Templates - Include - File Header

窗体的右侧便是头文件模板的编写窗口,具体编写方法右下方也有解释,就不过多解释了

设置成功后我们每次新建Java文件IDE便会自动帮我们补充适用于Javadoc的头文件注释,我们唯一需要做的便是补充Description条目即可

这样我们便解决了新建Java文件,头文件生成的问题,但我们别忘了那些原有的原有的Java文件,他们并不会跟着自动生成头文件,那么该怎么处理呢

🍃这时候我们便需要用到Live Tmplates功能,File - Setting - Editor - Live Tmplates

窗体的右侧编辑区的加号可以增加模板组或单个模板,一般我们先增加一个模板组,然后在模板组里编写各种模板,包括我们这里需要的头文件模板

解释下这个窗口的右下方的编辑区

  • Abbreviation:即你为这模板的命名,这个命名会成为你调用它的指令(比如你编写了名为一个doc_header的头文件模板,当你想使用它的时候,只需在文件的类名或接口名上一行输入doc_header,IDE便会弹出添加注释模板选项)
  • Description:对于这个模板的描述
  • Tmplate text:即编写模板的窗口,编写方法也很简单,只要记住被$符号包起来的会成为你需要编写的变量,可以点击Edit variables按钮对变量设置函数
  • Applicable in java:在这里设置模板使用的语言以及场景,选择java-declaration即可

为了老文件生成的头文件能够与新建文件的头文件格式一致,我们还是按照上面File Header的格式编写模板

具体模板如下:
/* Copyright (C) $YEAR$ Unicorn, Inc.
Description : Created by $USER$ on $DATE$ $TIME$.
*/

这里有一点需要注意,我这个版本的AndroidStudio目前还没有year()函数,所以这里暂时用date()代替下,每次生成后需要手动删掉date()的多余部分。

至此,AndroidStudio下适用用于Javadoc的头文件注释生成方法我们已经说完了,当然一个完整的Javadoc文档还有方法注释以及静态常态注释

🍃接下来我们来关注方法以及静态常量的注释怎么生成

可能你已经知道了,依旧是使用Live Tmplates功能,编写方法的模板;编写设置参数,返回值,异常等变量,然后为这些变量赋值函数

但其实这些函数是不会生效的,因为AndroidStudio暂时不支持自定义方法使用模板函数,也就是说对自定义方法使用这些模板,变量会是是空,这样就没有什么意义了(这个设定太坑了)

那我们该怎么做?天无绝人之路AndroidStudio中还藏有一个名叫Fix doc comment的方法

我们可以在Setting中直接搜索fix doc comment,我们需要做的就是双击给这个功能设置一个快捷键,这样我们就可以使它为我们的方法生成注释了

比如我们设置成Alt+反斜杠后,我们只需要将鼠标放在我们的自定义方法名上使用组合键即可

最终效果示例如下:
/* @param position 位置position
@param url 链接url @return 对象Picture
@throws Exception 抛出的异常 /
private Picture getPicture(int position, String url) throws Exception {
return new Picture();
}

还行,但是不是还少点什么,缺少一个描述!
这时候我们便可以使用Live Tmplates功能了,加一个方法的模板,名字设置为doc_methood,模板内容很简单
/**
*Description :
*/
连个变量都没有,因为变量Fix doc comment会帮我们补全的

所以我们如何给方法生成注释呢
先在方法名上一行输入doc_method生成一个简单的模板,然后按ctrl+反斜杠使用fix doc comment功能补全所有参数,一秒钟搞定

🍃最后至于静态常量,我们还是选择Live Tmplates为其便写个模板,格式与方法模板一样
/**
*Description :
*/


头文件,方法,静态常量注释都按照Javadoc要求编写,我们最终可以使用AndroidStudio的Generate doc功能输出一份Javadoc的文档,方便所有开发人员使用学习。

最后提及下方法内部注释,这些内容虽然不会录入Javadoc文档,为了美观还是建议有个规范

单行注释按照
//注释内容

多行注释按照
/*注释内容*/

这篇文章所使用的AS版本为2.3.3,仅供参考,欢迎大家指出其中所存在问题😁

Powered by Hexo and Hexo-theme-hiker

Copyright © 2013 - 2019 All Rights Reserved.

访客数 : | 访问量 :