这篇文章给大家分享的是Javadoc注释规范的相关内容。Javadoc是内嵌于JDK中的，因此了解清楚Javadoc注释规范是非常有必要的，文中介绍得很详细，有需要的朋友可以参考，接下来就跟随小编一起了解看看吧。

    1、什么是注释

    注释是为了使代码更具有可读性，降低团队合作的交流成本。    

    2、常用注释快捷键

    注释一行：//我是行内容    

    快捷键：ctrl+/ 反操作：ctrl+/注释一块：/*我是块内容*/

    快捷键：ctrl+shift+/ 反操作：ctrl+shift+\javadoc可识别的注释：

	/**
	 * 我是注释
	 * 我也是注释
	 * 我还是注释，我们都能被javadoc识别
	 */

    3、javadoc规范

    遵循javadoc规范，我们就可以使用javadoc命令，生成非常直观易读的API文档，非常方便。

    我们在程序中出现的注释可以有意识地分为两种，一种是简易的注释，给我们自己看的，一种是符合javadoc规范的注释，目的是生成易读的文档。

    仔细阅读生成的API文档，有三部分需要我们说明，如图：

    上面红框的内容都是我添加的注释，是一个简单的Hello类，源码如下，感兴趣可以自己去试试：

/**
  *	@author XXXX
  *	@version 创建时间：2021年1月21日 下午3:22:01
  *	
  */
public class Hello {

	/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}
	
	/**
	 * havaReturn方法就是为了测试javadoc注释规范的.
	 * <p>我发现只有有返回值的方法才可以使用return标签<br>
	 * 没有return硬是要用，只会在javadoc时候报错
	 * @param a 输入的第一个int类型的参数
	 * @param b 输入的第二个int类型的参数
	 * @return add 两个数的和运算结果
	 */
	public int haveReturn(int a,int b){
		int add=0;
		add=a+b;
		return add;
	}

}

    有几个要点需要指出：

    要想API文档出现作者和版本，不仅要在程序注释中添加@author和@version（需要说明的是，在程序多个地方注释@author也只会在最终文档中显示一次，我建议只注释一次），还要在编译的时候在dos命令中指出：
javadoc -d folder -version -author Hello.java    

    其中-d folder意思是你把生成的API文档（其实是很多网页组成的）放在folder文件夹中，当然folder也可以是个路径方法概要 与 方法详细资料 怎么区分呢？

/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}

    你一定发现关于方法的注释都是一大坨，javadoc如何提取概要呢？没错，就只靠一个dot(.)，观察我注释里面提到的那个dot，那就是提取概要的关键，dot之前是概要，所有的都是详细介绍（详细介绍是包含概要的）

    如何控制生成的文档中的注释排版

    我们在程序中能控制住的就是注释的排版，但是这种排版并不被javadoc识别，javadoc发现一行注释，只去掉*和空格之后，就一股脑传过去，注意到生成的文档是HTML类型的，所以只要在程序中注释HTML语法，就能实现编辑API文档格式，不要担心太困难，因为我们只是用一些简单的HTML语法，比如段落<p>，换行<br>这些就可以，毕竟注释也不会很长。

    @param 参数1 说明 （注意格式）

    @return 返回值 说明（注意格式）    

    有返回值就写，没返回值就不用写，写了反而会报错

    其实写类注释、方法注释非常简单，只要在类、方法前敲击/**，再按回车，系统就会自动添加，并且系统如何添加也是我们可以修改的

    如何修改新建文件时出现的内容，如何使自动补全的注释受我们控制（待办）

    我们从标准类文件中看到这个：

    我们都知道，out是System类的属性（字段），它是PrintStream类型的，类PrintStream中定义了很多方法，这些自然也是out的方法，因此在定义out的时候，它前面的注释中就有很多@see,这就是使用@see注释最好的地方，我们推荐在定义类的字段时，如果字段是复合类型的（特别是自定义的复合类型），那么就在前面注释@see,这样有两方面的好处，请看图：

    相信这两张图你都不陌生，第一个是写程序时候光标停留可以出现的提示，如果你按照javadoc规范来写注释，那么你自己写的程序也会出现这些极有帮助的提示。第二个是java8 API文档关于String类里的out字段的详细描述，这也是@see的功劳，你写了@see，你自己的项目API文档中也有这样的注释。

    关于Javadoc注释规范的内容就介绍到这，感兴趣的朋友可以了解看看，希望能对大家有帮助，想要了解更多Javadoc注释规范，大家可以关注群英网络其它的相关文章。

文本转载自PHP中文网

免责声明：本站发布的内容（图片、视频和文字）以原创、转载和分享为主，文章观点不代表本网站立场，如果涉及侵权请联系站长邮箱：mmqy2019@163.com进行举报，并提供相关证据，查实之后，将立刻删除涉嫌侵权内容。