javadoc规范介绍-LMLPHP

导语:

我们知道javadoc是内嵌于JDK中的,因此遵循javadoc规范肯定就是java注释的正统,有了javadoc帮助生成API文档是非常实用的。

(学习视频分享:java视频教程

1、什么是注释

注释是为了使代码更具有可读性,降低团队合作的交流成本。在一个团队中,你的代码更清晰、更易读,更规范,那么升职加薪肯定是你的,因为你可以兼容更多的人。
前段时间听到一个说法:你的代码写的只有你一个人看得懂,那你就是那个不可或缺的人。说这话的人就是脑残,写的代码只有自己看的懂得话,大家都不待见,活的像孙子一样,难道大家都需要孙子吗?

2、常用注释快捷键

注释一行://我是行内容
快捷键:ctrl+/ 反操作:ctrl+/注释一块:/*我是块内容*/
快捷键:ctrl+shift+/ 反操作:ctrl+shift+\javadoc可识别的注释:

	/**
	 * 我是注释
	 * 我也是注释
	 * 我还是注释,我们都能被javadoc识别
	 */
登录后复制

3、javadoc规范

遵循javadoc规范,我们就可以使用javadoc命令,生成非常直观易读的API文档,非常方便。
我们在程序中出现的注释可以有意识地分为两种,一种是简易的注释,给我们自己看的,一种是符合javadoc规范的注释,目的是生成易读的文档。
仔细阅读生成的API文档,有三部分需要我们说明,如图:

javadoc规范介绍-LMLPHP

javadoc规范介绍-LMLPHP

javadoc规范介绍-LMLPHP

上面红框的内容都是我添加的注释,是一个简单的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 返回值 说明(注意格式)
有返回值就写,没返回值就不用写,写了反而会报错

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

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

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

javadoc规范介绍-LMLPHP

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

javadoc规范介绍-LMLPHP

javadoc规范介绍-LMLPHP

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

相关推荐:java入门教程

以上就是javadoc规范介绍的详细内容,更多请关注Work网其它相关文章!

09-09 08:24