java的注释_java代码中包的注释是什么-CSDN博客

本文链接：https://blog.csdn.net/qq_37080070/article/details/79949423

首先先感叹一下，java真的是十分强大。

好，我们进入正题，java注释可谓是相当完善了，java的注释不但在实际源代码中的可读性相当好，而且还能够生成html甚至其他类型的配套文档。今天，我们就来看看如何使用java中提供的javadoc工具帮我们的代码生成一些十分专业和有用的文档。其实我们通常所查阅的API文档，就是对类库文件运行javadoc生成的，所以说，当你想查阅API文档却发现自己的计算机没有联网，而且你下载的离线文档也找不到的时候，可以使用javadoc自己做一个哦。。

下面，就来看看如何使用注释。

javadoc会从以下四个特性中抽取信息：

分别是包、公有类与接口、公有的和受保护的构造器和方法、公有的和受保护的域。

注释的形式都一样，都是/**... ...*/的形式，其中在/**后紧跟的是自由文本,自由文本中可以使用HTML修饰符，例如<em>...<em>,<strong></strong>,<img...>等，但是不能使用<h1>或<hr>因为这样会产生冲突，如果要写入等宽代码，需要使用{@code...}。然后后面可以跟各种标记，例如@author,@version

下面就来说明一下各种注释的位置：

首先是类注释：类注释需要放在import语句之后，类定义之前。

然后是方法注释：方法注释必须放在所描述的方法之前。

再就是域注释：放到域的前面

最后是包注释：提供一个以package.html命名的HTML文件（将描述内容放入<body></body>中）或者提供一个package-info.java的文件（对哪个包进行注释，就要在这个文件中加入注释信息，并在最后写一行package 包名）。

上面提到了标记：标记可以更加清楚使我们的描述源文件，所有的标记并不多，下面来介绍一下常用标记的详细使用方法。

首先来看看它们的作用吧

标记分为通用标记和专门的标记，比如说方法注释中可以使用@param和@return标记，而包注释中却没有，这很好理解，包当然不会有参数和返回值了。。。。而它们却有共同的标记如@author，因为它们都是人写的。

首先是通用标记

（1）@author：这个标记会产生一个作者条目，使用方法为 @author 作者名当然，允许在同一个注释中插入多个作者

（2）@see：这个标记会产生一个链接，后面的参数可以以下形式之一：

--包名.类名#方法名(参数)

--一个超链接

--"文本"

当然也可以使用{link args}来替代，这个形式的优势是可以放在注释的任何部分，其中args是上面3种形式之一。（什么，为什么我的只能引用第一种，这可能是javadoc的版本不一样，不用担心，没办法。。。博主我的就不行，但书上说可以，我也是醉了）

（3）@category：表示属于哪一类

（4）@since：这个标记将产生一个"since"（始于）条目。使用方法为 @since 文本这里的文本可以是对引入特性的版本描述。例如：@since fun方法的参数由int替换为Integer

然后是专门的标记

（1）@deprecated：这个标记将对类、方法或变量添加一个不再使用的注解。文本中给出了取代的建议。

例如@deprecated Use <code>setVisible(true)</code> instead +（@see或@link的引用）

还有一个比较重要的是，一个方法会有@exception、@throws、@param、@return等经常用的注解，具体顾名思义，不再解释。

具体生成文档和进一步了解java注释的有关内容请参阅人参米博主的文章

以下是一个例子以及生成的文档效果：

代码：

AnnotationTest.java

package Annotation;

import java.util.ArrayList;
/**
 * （类注释）该类演示了如何使用Java的各种注释
 * @author Administrator
 * @version 1.0
 * 
 */
public class AnnotationTest {
	
	/**
	 * (域注释)一个常量，圆周率
	 * 
	 */
	public static final double PI=3.1415926535;
	
	/**
	 * 
	 * 一个static域
	 */
	public static int t=7;
	
	/**
	 * 
	 * （方法注释）该方法将字符串容器中的字符挨行输出，并返回字符串的总数量
	 * @param sList 要进行输出的字符串容器的引用
	 * @return 容器中字符串的数量
	 */
	public static int output(ArrayList<String> sList) {
		int count=0;
		for(String s:sList) {
			System.out.println(s);
			++count;
		}
		return count;
	}
	
	/**
	 * （方法注释）这个不用多说了，main方法
	 * @param args 运行时参数
	 */
	public static void main(String[] args) {
		
	}

}

package-info.java

/**
 * 
 */
/**
 * （包注释）该包系统的演示的各种注释的使用方法
 * 
 */
package Annotation;

下面是生成文档的效果图：

参考资料：java核心技术第9版