关于IDEA注释格式

开发过程中经常看到源码中的注释，感叹大佬的注释为何写得那么清新脱俗，决定简单研究一下IDEA中的注释

众所周知，Java中的注释标识分为三种：

//       [1]
/* */    [2]
/** */   [3]

第一种是单行注释 //之后的部分皆为注释
第二种和第三种注释可以将注释内容限制在斜杠之间，这是单行注释无法完成的

    public void setNameAndAge(/*名称*/String name, /**年龄*/String age){
        this.name = name;
        this.age = age;
    }

第二种注释用的相对较少
这里主要说一下第三种注释：/** */的情况，这是可以被javadoc所识别的注释，即这种注释可以被JDK中的文档工具所感知，从而实现注释的抽取等操作。
e.g.

我们还可以通过javadoc命令对第三种注释中的内容进行抽取，整合成一个文档，由于这些知识点非常General, 随处可见，不谈。

言归正传，本文只涉及第三种注释，主要内容分为以下部分：

1. 注释的显示状态切换
2. 如何在注释中添加超链接
3. 制表符的添加
4. IDEA中其它常用的HTML标签

注释状态切换：

之前看大佬们的注释都是:



而我的注释：





为何源码中别人的注释和自己写的注释显示效果完全不一样呢 其实是设置问题而已(今天才知道… 尴尬了)



点击图中的铅笔就可以切换为注解源码，效果如下：





再点击图中左上角的图标就切换回了注释的阅览视图

---

注释中添加超链接的方法：
(1) 使用@see
场景：
有类Student:

package com.test.springbatch.query;

import lombok.Data;

@Data
public class Student {
    private String name;
    private String age;
    public String pub;
    public void printWords(String words){
        System.out.println(words);
    }
}

在类User的注释中加入指向Student类以及其中属性和方法的超链接:

图中的5个@see注解后的链接分别指向Student类、age属性、pub属性、getName方法、printWords方法 需要注意的是#age会被标红，因为age是private的，但这不对链接的功用产生影响
点击左上角的图标切换为阅览视图之后：

此时点击指定的链接即跳转至指定的Class/Field/Method

(2) 使用@link

切换视图后：

---

plus: 注释中制表符的实现：

加上li标签即可, 效果：

注意 ： 使用<li>时最好用<ul>标签作为其父标签：

/**
 * <ul>
 * <li> sss
 * <li> sss
 * <li> sss
 * </ul>
 */
public class User {
    private String name;
    private String age;

    public String getName(){
        return "";
    }
}

不写<ul>默认也为无序列表
若用<ol>做父标签则为有序列表：

/**
 * <ol>
 * <li> sss
 * <li> sss
 * <li> sss
 * </ol>
 */
public class User {
    private String name;
    private String age;

    public String getName(){
        return "";
    }
}

效果：

---

除上述的制表符，IDEA中的注释中还可使用其它常用的标签

• <em></em> ；<i></i>对Html稍有了解的人都知道这两个标签，效果为使字体倾斜。

/**
 * hello, today is <em>SUNDAY</em>!
 * hello, today is <i>SUNDAY</i>!
 */
@Data
public class User {
public class User {

效果：

图中SUNDAY字样被倾斜显示。

• <p> 标签，该标签无特殊显示效果，仅仅作为段落开始的标志

/**
 * <p>
 * hello world
 * 
 * hello world
 */
@Data
public class User {

效果：

可见<p>标签下的内容作为一个段落，并不会如原注释般换行

当写为：

/**
 * <p>
 * hello world
 * <p>
 * hello world
 */
@Data
public class User {

效果为：

此时两个hello world从属于不同的<p>,故具有换行效果。
plus: 需要注意，不使用p标签 注释文字默认也是不换行的：

/**
 * hello world
 * 
 * hello world
 */
@Data
public class User {

效果：

• <pre class="code"> 标签 如同Markdown中写代码需要使用使用代码块一样，注释中若需要写代码的话可用此标签

/**
 * <pre class="code">
 *   &#064Configuration
 *   class A{
 *     private String name;
 *     private String age;
 *
 *   }
 * </pre>
 */
@Data
public class User {

注意，代码块中某些特殊字符需要进行转义处理，图中的&#064是@转义后的字符，否则无法被识别。效果：

---

End