编写和生成标准的 JavaDoc 文档是 Android 开发过程中很重要的一个技能，这个关系到代码的可维护性，还有如果自己有封装第三方库，方便调用者阅读。
Runtime Environment
OS: Mac OS X 10.10.3
eclipse: ADT Bundle
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 的话，建议从创建者开始，依次往后排的顺序。
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]。
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.不用标记，一般是用脚本整体编译标记。
1.用来标记是在当前版本，可以标记在包[package]、类[class]、接口[interface]。
2.不用标记，一般是用脚本整体编译标记。
/** * @param bluetoothDevice 蓝牙设备。 * @param status 状态。 */
@param
1.用来标记参数，可以标记在方法[method]和构造器[constructor]中。
2.如果是多个参数的话，请保持和传入方法中的参数保持一致。
1.用来标记参数，可以标记在方法[method]和构造器[constructor]中。
2.如果是多个参数的话，请保持和传入方法中的参数保持一致。
/** * @return 歌曲数量。 */
@return
1.用来标记方法的返回值，只标记在方法[method]中。
1.用来标记方法的返回值，只标记在方法[method]中。
/** * @see BluetoothManager */
@see
1.用来标记参见，可以标记在包[package]、类[class]、接口[interface]、方法[method]、成员变量[member variable]。
2.如果是多个@see的话，建议从“最近到最远”！
3.@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 **}标记被替换后的内容。
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 则不需要。
1.用来标记索引内容，可以标记在包[package]、类[class]、接口[interface]、方法[method]、成员变量[member variable]。
2.@link 是需要用大括号的。而 @see 则不需要。
/** * @自定义TAG */
@自定义TAG
1.用来表示自定义的JavaDoc标注。
2.如果你的标注tag和annotation冲突的话，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>来格式化代码。
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键+鼠标点击，来判断索引的链接是否有效，这样的做法是不行的。如果方法名错误或者不存在的话，点击还是会跳转的，只不过会跳转到对应的上一层存在的内容。
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的不可映射字符” 的错误分析及解决方法！
微信扫一扫，打赏作者吧～
