注释与嵌入文档

​ 在写项目中，有一个良好的注释习惯是非常用必要的，它可以增加程序的可读性和可维护性，不要觉得这是在搬书本上的话，我深有体会。因为在刚来公司实习的时候，那项目代码完全不知道有什么作用，注释就是很简单的一句话。我也没有良好的注释习惯，导致项目经理说我代码都可以不写，但是注释一定要写！

---

​ 在看 《java编程思想》 的时候，第2章最后一小节专门有讲如何生成javadoc文档。于是我学了以后，就在项目中开始锻炼使用，这里记录一下：

• 普通注释：这是我们常用的注释方法
• // 单行注释
• /* */ 多行注释
• 注释文档 ：/** */和javadoc 命令结合使用，同时可以嵌入html标签，最后生成html文件。注意生成文件中只有public和protected 修饰的成员注释。
  • 标签 < pre > ; < ol>< li>
  • doc命令
    • @see 引用其他类。类名#方法，可用于类、方法、成员变量
    • 类文档标记：@author、@version、普通文字描述
    • 方法文档标记：@param、@return、@thorws 、@author、@date、普通文字描述

我之前只是觉得这些标记单纯的为了看注释，原来还有一个很大的作用是生成 html 文档，并且也知道了 /** */是什么含义

撸代码：

package study.basic.demo02;

/**
 * 模板注释测试，描述类的作用
 * @author Jingyang Yao
 * @version 1.0
 * @date 2021/9/22
 */
public class Animal {

    /**
     * 这是一个说话的方法
     * @param str 要说的话
     * @param str1 第二句话
     * @return 两句合并说出来的话
     * @throws Exception 说话异常
     * @author Jingyang Yao
     * @date 2021/9/22
     */
    public String  say(String str,String str1) throws Exception{
        return str+str1;
    }
}

---

**在IDEA中可以生成 html 文档**

工具栏 Tools → Generate JavaDoc → 设置要生成的文件 和 生成路径 ，在 other command line arguments 栏 指定编码 -encoding UTF-8 -charset UTF-8