Android 编写 JavaDoc 文档的总结 2015-08-27 / 5,274 次 / 快抢沙发 /

编写和生成标准的 JavaDoc 文档是 Android 开发过程中很重要的一个技能,这个关系到代码的可维护性,还有如果自己有封装第三方库,方便调用者阅读。

Runtime Environment
OS: Mac OS X 10.10.3
eclipse: ADT Bundle
编写和生成标准的 JavaDoc 文档是 Android 开发过程中很重要的一个技能,这个关系到代码的可维护性,还有如果自己有封装第三方库,方便调用者阅读。

现在对 JavaDoc 中常用的标记做一个说明:

/**
* @author ifeegoo
*/
@author
1.这个一般是用来标记作者的。只能用在包[package]、类[class]和接口[interface]上。
2.假若有一个组织[smart code united]一起开发了一个框架,比如 com.smartcodeunited.*,这个时候可以在包[package]级别下标注 @author Smart Code United,而在某个类[class]或者接口[interface]下面标注具体成员。
3.如果有多个 author 的话,建议从创建者开始,依次往后排的顺序。
/**
* @since 1.0.0
*/
@since
1.用来标记是在什么版本引入的,可以标记在包[package]、类[class]、接口[interface]、方法[method]、成员变量[member variable]。
2.只要当前包[package]、类[class]、接口[interface]、方法[method]、成员变量[member variable]不被删除,就不用更新@since,哪怕是访问修饰符的变化。
3.个人建议,尤其是写第三方库的时候,标注每一个包[package]、类[class]、接口[interface]、方法[method]、成员变量[member variable]。
/**
* @since version
*/
@version
1.用来标记是在当前版本,可以标记在包[package]、类[class]、接口[interface]。
2.不用标记,一般是用脚本整体编译标记。
/**
* @param bluetoothDevice 蓝牙设备。
* @param status 状态。
*/
@param
1.用来标记参数,可以标记在方法[method]和构造器[constructor]中。
2.如果是多个参数的话,请保持和传入方法中的参数保持一致。
/**
* @return 歌曲数量。
*/
@return
1.用来标记方法的返回值,只标记在方法[method]中。
/**
* @see BluetoothManager
*/
@see
1.用来标记参见,可以标记在包[package]、类[class]、接口[interface]、方法[method]、成员变量[member variable]。
2.如果是多个@see的话,建议从“最近到最远”!
3.@see不用加大括号。
@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id...)
@see #method(Type, Type,...)
@see #method(Type id, Type, id...)
@see Class
@see Class#field
@see Class#Constructor(Type, Type...)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type id, Type, id)
@see package
/**
 * @deprecated  As of JDK 1.1, replaced by
 *              {@link #setBounds(int,int,int,int)}
 */
@deprecated
1.用来标记是在当前版本,可以标记在包类[class]、接口[interface]、方法[method]、成员变量[member variable]。
2.注意@deprecated的使用前提:非安全,有bug或者效率低。将来版本会被移除,或者会导致不良编码习惯的。
3.尤其是当一个SDK发布了正式版本之后,千万不要随意的修改和删除相关内容,只能用@deprecated。
4.请在后面用{@link **}标记被替换后的内容。
/**
* {@link BluetoothDeviceManager}
*/
@link
1.用来标记索引内容,可以标记在包[package]、类[class]、接口[interface]、方法[method]、成员变量[member variable]。
2.@link 是需要用大括号的。而 @see 则不需要。
/**
* @自定义TAG
*/
@自定义TAG
1.用来表示自定义的JavaDoc标注。
2.如果你的标注tag和annotation冲突的话,tag优先。如果你想两者都生效的话,你可以命名成不一样的名字。

另外一个比较重要的点,就是对 {@link *} 和 @see 的索引的说明。

/**
*<p>{@link #setParams(int, int)}
*</p>
*
* @see       #create(int, int, int, int)
* @see       Component#update(Graphics)
* @since     1.0
*/
public abstract void dispose();

上面的例子中:方法前面一定要带上”#”号,类和接口的话还是正常来写,另外在方法平行的情况下,可以省略前面的类名。如果是平行一级的内部类、接口与方法之间的互相调用,建议带上全称。

另外一个需要注意的地方就是内容描述:
1.内容描述我们一般采用HTML标签。
2.内容可以用段落标签<p></p>来标记。如果要强调的话,就用<strong></strong>标签。
3.其他的就是正常的HTML标签。
4.可以使用<pre class=”prettyprint”></pre>来格式化代码。
请注意生成JavaDoc的工具版本,版本越新越好,版本旧的,有些错误根本不提醒,比如Mac系统下Java1.6版本的JavaDoc工具,很多的错误不提醒!

我们如何来判断我们的 JavaDoc 注释写的是否有误?很简单,我们通过 eclipse 自带的生成 JavaDoc 的工具。在这个过程中,如果发现我们的 JavaDoc 注释有错误的地方,会在生成过程中,通过日志来提醒我们。我们便可以快速定位到哪里出错!

JavaDoc出错常见的原因:
1.索引的出错。
[类名、方法名等写错,或者索引不存在]
[方法前面不该省略接口名或者方法名]
[索引了之后,没有导入对应的包]
[如果导入对应的包还是没有效果的话,带上这个类的包结构,比如{@link android.util.Log}]
2.忘记标注的内容。
[方法需要标注 @param 和 @return,如果有的话!]
3.标记了却没有内容。
[比如写了 @see @return,却没有写相关对应的内容。]
4.在不该标记的地方标记。
[不能在方法处标记 @author]
说明:不要尝试的在写完之后,用Command/Ctrl键+鼠标点击,来判断索引的链接是否有效,这样的做法是不行的。如果方法名错误或者不存在的话,点击还是会跳转的,只不过会跳转到对应的上一层存在的内容。

相关参考内容:
How to Write Doc Comments for the Javadoc Tool
eclipse:导出 Javadoc 出现”程序包 android.* 不存在”错误分析及解决方法!
eclipse:导出 Javadoc 出现 “编码GBK的不可映射字符” 的错误分析及解决方法!

打赏
本博客所有文章如无特别注明均为原创。复制或转载请以超链接形式注明转自ifeegoo,原文地址《Android 编写 JavaDoc 文档的总结
上一篇: « 下一篇: »
Copyright © ifeegoo Time is limited, less is more! / 粤ICP备15109713号 / Theme by Hang & Ben / WordPress / 知识共享许可协议