java备注后加文本yu_java之禅--注释

一、代码注释

1.什么是注释？

所谓注释，并不是一堆废话。而是对你的程序的一种简明扼要的解释。比如注释可以用来描述你所写的类的相关信息，描述这个类中某个方法的作用，方法中的参数意义，以及返回值等信息

2.有哪些类型的注释？

注释有3种： 单行注释： //注释内容 多行注释 ：/* 注释内容 / 文档注释： /* 注释内容 */

public class Demo{

// 这是单行注释

String str="Hello World!";

/*

这是多行注释

*/

String str1="多行注释";

/**********文档注释如下：**********************/

/**

* @param session :

* @param productId :

* @param productCount :

* @Description: 添加购物车

* @return: com.mmall.common.ServerResponse

* @Author: yqy

* @CreateDate: 2019/11/17 17:18

*/

@RequestMapping("addCart.do")

public ServerResponse addCart(HttpSession session, Integer productId, Integer productCount) {

User user = (User) session.getAttribute(Const.CURRENT_USER);

if (null == user) {

return ServerResponse.createByError(ResponseCode.NEED_LOGIN.getCode(), ResponseCode.NEED_LOGIN.getDesc());

}

// 如果用户已登录，则加入购物车

ServerResponse cartServerResponse = cartService.addCart(user.getId(), productId, productCount);

return cartServerResponse;

}

}

重点在于文档注释：

JDK的API文档存放路径： 下载java SE Document，然后 解压 jdk-8-doc.zip会得到一个docs的文件夹，即可得到API文档

注意：开发过程中，我们在定义类和方法时可以添加文档注释，然后通过javadoc命令生成 API文档，API文档主要是用于 说明类，方法，属性的功能。而且javadoc工具默认只处理public 或者 protected修饰的类、接口、方法、属性、构造器的文档注释。

如果需要提取private修饰的内容，在使用javadoc 命令时增加 -private选项

javadoc 命令用法即参数详细说明：

javadoc -d 存放该api文档的路径 -windowtitle 浏览器窗口标题 -doctitle 文档标题 -header 左边的标题 -version -author 类名.java (注意：如果要生成这个文件下所有的java类的API，那么，就可以使用通配符 *.java 来代替 类名.java)

文档注释中常用的javadoc标记：

@author 作者 @version 版本 @param 方法参数说明 @return方法返回值@exception抛出异常的类型 @throws 抛出的异常，exception作用相同

使用javadoc 命令时报错：编码GBK的不可映射字符

问题原因：类文件中带有非GBK字符

解决办法：给javadoc命令带上 -encoding参数，如 javadoc -encoding utf-8