java注释的分类
1、单行注释：int SUM = 100; //这是一个单行注释
2、多行注释：
/*
*这是一个多行注释
*/
3、文档注释：
/
*这是一个文档注释
* @return a
*/
java注释和文档注释
作为一个java程序员我们一定都喜欢看官方的开发文档，文档中很详细的包括了类和接口参数方法等信息，并提供了许多类之间的关系等等。java的开发文档是由HTML页面进行展示的，但是用了很久我们才知道，这些文档实际上不是一点一点的写出来的，我们自己也可以进行生成。
安装了 JDK 之后，安装目录下有一个 src.jar 文件或者 src.zip 文件，它们都是以 ZIP 格式压缩的，可以使用 WinZip 解压。解压之后，我们就可以看到分目录放的全是 .java 文件。是了，这些就是 Java 运行类的源码了，非常完整，连注释都写得一清二楚，我们可以对比这里的注释和开发文档，以java.util.List为例：这是官网API截图
接下来再看一下源码信息：
…..
* @param
the type of elements in this list
*
* @author Josh Bloch
* @author Neal Gafter
* @see Collection
* @see Set
* @see ArrayList
* @see LinkedList
* @see Vector
* @see Arrays#asList(Object[])
* @see Collections#nCopies(int, Object)
* @see Collections#EMPTY_LIST
* @see AbstractList
* @see AbstractSequentialList
* @since 1.2
*/
public interface List
extends Collection
{
…..
}
可以看出来，java的开发文档其实就是在将代码中的注释按照相应的规则整理出来的，这对程序的阅读者和使用者十分关键，由此可见，学会写注释对于一个程序员来说是十分关键的，也能体现一个程序员的水平。
文档和文档注释的格式
文档注释可以用在类，方法，属性上进行说明。文档内部要注意细节问题。
因此，格式化文档，就是在注释中添加HTML相应的标签。
*注意，文档说明后面需要紧跟类、接口、方法或属性
文档注释的三个组成部分
第一个部分作为类、接口、方法、属性的简述。简述在文档注释的最前面，简述的末尾需要加上一个点号“.”，就是使用点号来分割文档注释，有的时候点号会出现错误，我们就用
作为第二部分的开头进行分割。
第二部分就是注释的详细部分，对属性或方法等进行详细的说明，在格式上没有什么特殊的要求。
第三部分是特殊说明部分，这个部分包括声明作者、版本说明、参数说明、参考说明、返回值说明。抛出异常说明等，这一部分最好和第二部分有一个空行，不然可能会出现错误。 
常用的javadoc标记及其使用
1、@see的使用：
@see的句法有三种
①、@see 类名
类名可以根据需要只写出类名，如String，或者写出全名：java.lang.String，但需要注意的是，在用类名的时候需要这个java源文件中import这个类，否则只能用全名。
②、@see#方法名或属性名
如果是属性名，则只需要写出属性名即可，如果是方法名，则需要写出方法名以及参数类型，如果没有参数，也需要写出一对括号。
如：@see #contains(Object)、@see #count()、@see number
③、@see 类名#方法名或属性名
如：@see Object#equals(Object)、@see java.lang.String#toString()
2、@author、@version的使用：
这两个标记分别指明作者和版本号，缺省情况下javadoc自动将其忽略，但命令行开关-author和-version可以修改个功能，使其包含的信息流输出，这两个标记都可以多个使用，但是版本号只有第一个出现的有效。
3、@param、@return和@exception的使用：
这三个标记只能用于方法，@param描述参数，@return描述返回值，@exception描述抛出异常，用法如下：
①、@param 参数名 参数说明
②、@return 返回值说明
@exception 异常类名 异常说明
@exception可以多次使用，并且异常的类名需要注意在java原文件中是否有导入，如果没有需要写类全名。
如：
javadoc命令
用法：javadoc [options] [packagenames] [sourcefiles]
选项：
也可以给出源文件列表，如：javadoc xcg/test/JavaDocTest.java
以上两种方式的编译结果不同，用包列表生成的文档被框架分成了三个部分：包列表、类列表和类说明
在eclipse或myeclipse中可以使用file->Export->javadoc可以进行手动输出javadoc，需要注意生成的时候可能会出现错误: 编码GBK的不可映射字符，这时就需要在流程的最后一步加上一句话控制字符：-encoding UTF-8 -charset UTF-8，如：
注释规范
1、注释原则：
①注释形式统一
②注释内容准确简单
2、注释条件：
①基本注释（必须加）：类、接口的注释、构造函数的注释、方法的注释、全局变量的注释、字段/属性的注释
发布者：全栈程序员-站长，转载请注明出处：https://javaforall.net/216741.html原文链接：https://javaforall.net
