[Java]重学Java-文档注释

文档注释

刚开始学习Java的时候，觉得注释是很啰嗦的东西，但是随着编码的时间增长，觉得注释是很重要的东西。写好注释，是成为一名高素质的编程人员必备能力。今天，我们来看看Java中的一些Javadoc.

Javadoc可以在代码上编写HTML文档注释，使用javadoc工具可以导出代码文档，或者在新版的IDEA里面，你可以直接看到经过HTML处理过后的文档内容.

• String源码的文档注释

string

• String源码的HTML文档

string

可以看到，写的好的javadoc文档，经过HTML解析后，可读性是非常高的

文档注释需要表达什么

1. 类的职能
2. 简单的用法可以适当写一下
3. 与之关联的类，可以用@see进行导航
4. 注意事项
5. 作者
6. 编写类的版本号或者日期

HTML修饰符

斜体-em

/**
 * com.tea.modules.java8.annotation <br>
 * <em>这是一段被强调的内容</em>
 * @author jaymin
 * @since 2021/5/25
 */
public class JavaDocDemo {
}

• 效果图

em

加粗-strong

/**
 * com.tea.modules.java8.annotation <br>
 * <em>这是一段被强调的内容</em>     <br>
 * <strong>这是一段被加粗的内容</strong>
 * @author jaymin
 * @since 2021/5/25
 */
public class JavaDocDemo {
}

• 效果图

strong

嵌入代码块-{@code}

/**
 * com.tea.modules.java8.annotation <br>
 * <em>这是一段被强调的内容</em>     <br>
 * <strong>这是一段被加粗的内容</strong>
 * 
 * <pre>{@code
 *    System.out.println("Hello,world");
 *    System.gc();
 * }</pre>
 * @author jaymin
 * @since 2021/5/25
 */
public class JavaDocDemo {
}

• 效果图

code

链接外部类-{@link}

/**
 * com.tea.modules.java8.annotation <br>
 * <em>这是一段被强调的内容</em>     <br>
 * <strong>这是一段被加粗的内容</strong>
 *
 * <pre>{@code
 *    System.out.println("Hello,world");
 *    System.gc();
 * }</pre>
 * 这是空指针异常: {@link NullPointerException}
 * @author jaymin
 * @since 2021/5/25
 */
public class JavaDocDemo {
}

• 效果图

link

类注释

作者-@author

/**
 * com.tea.modules.java8.annotation <br>
 * <em>这是一段被强调的内容</em>     <br>
 * <strong>这是一段被加粗的内容</strong>
 *
 * <pre>{@code
 *    System.out.println("Hello,world");
 *    System.gc();
 * }</pre>
 * 这是空指针异常: {@link NullPointerException}
 * @author jaymin
 * @since 2021/5/25
 */
public class JavaDocDemo {
}

• 效果图

author

编写代码的起始日期-@since

/**
 * com.tea.modules.java8.annotation <br>
 * <em>这是一段被强调的内容</em>     <br>
 * <strong>这是一段被加粗的内容</strong>
 *
 * <pre>{@code
 *    System.out.println("Hello,world");
 *    System.gc();
 * }</pre>
 * 这是空指针异常: {@link NullPointerException}
 * @author jaymin
 * @since 2021/5/25
 */
public class JavaDocDemo {
}

• 效果图

since

引用-@see

/**
 * com.tea.modules.java8.annotation <br>
 * <em>这是一段被强调的内容</em>     <br>
 * <strong>这是一段被加粗的内容</strong>
 *
 * <pre>{@code
 *    System.out.println("Hello,world");
 *    System.gc();
 * }</pre>
 * 这是空指针异常: {@link NullPointerException}
 * @see JavaDocDemo
 * @author jaymin
 * @since 2021/5/25
 */
public class JavaDocDemo {
}

• 效果图

see

标明版本号-version

/**
 * com.tea.modules.java8.annotation <br>
 * <em>这是一段被强调的内容</em>     <br>
 * <strong>这是一段被加粗的内容</strong>
 *
 * <pre>{@code
 *    System.out.println("Hello,world");
 *    System.gc();
 * }</pre>
 * 这是空指针异常: {@link NullPointerException}
 * @see JavaDocDemo
 * @author jaymin
 * @since 2021/5/25
 * @version JDK1.8
 */
public class JavaDocDemo {
}

• 效果图

version

方法注释

参数-@params

标明方法参数意义

返回值-@return

写清楚方法返回什么类型的值

异常-@throws

描述可能会抛出的异常

/**
 *
 * @param code 状态码
 * @param msg 信息
 * @return String
 * @throws Exception 可能会抛出异常
 */
public String demo(Integer code, String msg) throws Exception {
    return "";
}

• 效果图

methodDocument