java jar注释被删除 java里面的注释

转载

墨染心语 2024-07-24 20:35:31

文章标签 java jar注释被删除 Java java javad 文章分类 Java 后端开发

前言Java 之 Annotation(注解)介绍

之前有写过一篇 Java 注解的介绍。参考以上链接。

虽然注解、注释只相差一个字，但是用法就差异很大。

总体一句话，注解给编译器看，注释是给人看的。

基于此的话，对于一个方法来说：

1. 把这个方法的作用，输入，输出描述清楚就可以了，更多的可以加上一些作者呀，版本呀这样一些信息

2. 注释编排的美观一些

做到这两点应该就可以了。举个例子：

/*******************************************************************************
	* NAME:			usage
	* DESCRIPTION:	XXX
	* ARGUMENTS:	N/A
	* RETURN:       
	* AUTHOR: 		oscar999
	* VERSION:      V0.1
	*******************************************************************************/

看上去这是一个不错的注释^^.

但是对于Java 语言来说，注释被赋予了更多的功能。就是你可以使用javadoc 这个功能把代码中的注释导出到 html 的文件中。

如果你的代码是共用性很高的代码的话，这份文档就是一份API的参考文档，类似Java API.

所以，要产生出这样的文档，就要遵循java 定义的一些注释规范，才能产生出规范的文档出来。

Java 类方法的标准注释

还是从类的方法的注释说起。

/**
     * Read a line of text.  A line is considered to be terminated by any one
     * of a line feed ('\n'), a carriage return ('\r'), or a carriage return
     * followed immediately by a linefeed.
     *
     * @param      ignoreLF1  If true, the next '\n' will be skipped

     * @param      ignoreLF2  If true, the next '\n' will be skipped

（不去关注以上注释的意义，只关注其定义的样式）

1. 首先看最上面的 “Read a line of text. A line .. ” 这一段是对这个方法的一些描述。

第一个句号前面的部分，也就是 “Read a line of text.” 会出现在 “方法摘要” 中

java jar注释被删除 java里面的注释_Java

全部的描述信息会出现在“ 方法详细信息” 中

java jar注释被删除 java里面的注释_javad_02

2. @param 定义的是方法的输入参数，（可以添加多个）出现在“ 方法详细信息” 中。（参数和参数描述之间使用空格隔开，在产生的文档中转成了 -）

java jar注释被删除 java里面的注释_java_03

3. @return 返回值的描述

4. @see 参考的描述

5. @exception 异常抛出的描述

美观考虑，不同类的标签可以换一行显示，比如 @param 和 @return 直接空一行。

Java 类标准注释

类的注释和方法注释的格式基本相同。区别的地方：

1. 放置的位置不同。类的注释放在类定义的上面，方法的注释放在方法定义的上面。

2. 类的注释比较会使用 @version @author @since 这样的标签。

看模板

/** will buffer the input from the specified file.  Without buffering, each
* invocation of read() or readLine() could cause bytes to be read from the
* file, converted into characters, and then returned, which can be very
* inefficient. 
* 
* 
* Test Description
* 
* <p> Programs that use DataInputStreams for textual input can be localized by
* replacing each DataInputStream with an appropriate BufferedReader.
*
* @see FileReader
* @see InputStreamReader
*
* @version 	0.1, 11/20/13
* @author	oscar999
* @since	JDK1.5
*/

doc 中显示的效果是：

同样，描述的第一句出现在“类概要”中。

java jar注释被删除 java里面的注释_java_04