Java的文档注释

这一段时间在看Java源码以及别人的一些代码时总会看到一些用 @ 修饰的东西。以前最熟悉的就是@override重写，但当我看到这个

真的可以说是被“震惊”了，所以打算来学习一下Java的文档注释。

---

Java 支持三种注释方式。前两种分别是 // 和 /* */，第三种被称作说明注释，它以 /** 开始，以 ***/**结束，前两种都是都是非常熟悉的了，最有意思的是第三种说明注释。

Java标签

这里只列举几个常见的Java标签

标签	描述	示例
@author	标识一个类的作者	@author description
@return	说明返回值类型	@return exp
@param	说明一个方法的参数	@param parameter-name exp
@exception	标志一个类抛出的异常	@exception exception-name exp
@throws	和 @exception标签一样	同上
@serial	说明一个序列化属性	@serial description

Java的文档注释

在开始的 /** 之后，第一行或几行是关于类、变量和方法的主要描述。

之后，你可以包含一个或多个各种各样的 @ 标签。每一个 @ 标签必须在一个新行的开始或者在一行的开始紧跟星号(*)。多个相同类型的标签应该放成一组。

下面举个例子：

/**
 * 表层数据库访问
 */
public interface OrderInterface {
    /**
     * 获取全部订单
     * @param a 起始位置
     * @param b 末位置
     * @return 列表？
     */
    List<Orders> pageList(int a, int b);

    /**
     * 获取全部行数
     * @return int
     */
    int pageCount();

    /**
     * 通过ID查询订单
     * @param id 订单号
     */
    List<Orders> pageListById(int id);

    /**
     * 通过日期时间查询订单
     * @param d1 起始时间
     * @param d2 截止时间
     */
    List<Orders> pageListDate(String d1, String d2);

    /**
     * 通过menu查询订单
     * @param name ？
     */
    List<Orders> pageListMenu(String name);

    /**
     * 通过id更新delivery
     * @param id
     * @return
     */
    int updateDeliveryById(Integer id);

    /**
     * 通过ID删除订单
     * @param id 订单ID
     */
    int deleteById(Integer id);

    /**
     * 通过delivery查询订单
     * @param delivery ？
     */
    List<Orders> pageListByDelivery(Integer delivery);

    int insert(Orders orders); // 增加order
}

利用 /** 和 @ 进行注释以及打标签方便了我们在阅读代码时可以更清楚了解该方法的作用，同时我认为最大的帮助是在用IDEA写代码时

当我们不确定一个方法或类的作用时只需将鼠标放在上面便会d出提示框，提示的内容取决于你写的标签。上图我的注释是这样写的：

/**
     * 获取全部订单
     * @param a 起始位置
     * @param b 末位置
     * @return 列表？
     */

---

JavaDoc给的注释确实实用，但我们每次用起来还是会特别的麻烦，其实我们可以自定义成模板在 IDE 上，这样每次通过快捷键就可自动帮你输出在方法中，省去了很多时间，也使代码更加规范。

如何自定义模板？可以参考这几篇博客：

• IDEA工具第二篇：自定义Java注释模板
• IDEA中如何自定义注释模板