关于java:Java-注释规范

2次阅读

共计 1560 个字符，预计需要花费 4 分钟才能阅读完成。

我是清都山水郎，天教懒慢带疏狂。曾批给露支风券，累奏流云借月章。
诗万首，酒千觞，几曾着眼看侯王。玉楼金阙慵归去，且插梅花醉洛阳。

好的正文往往能缩小提供协同开发的工作效率，以及极大的晋升零碎的可维护性。因而写好代码正文也是一个很重要的事件。
Javadoc 个别分为三段：

第一段：概要形容
通常用一句话形容类或办法的作用，且以 . 结尾
第二段：详细描述
第三段：文档标注，用于标注作者、创立工夫、参阅类等信息。

效果图

以下只介绍罕用的正文

标签	形容	作用域
@author	标注类的作者	类
@deprecated	标注类或者办法过期	类、办法
@exception	标注办法抛出的异样	办法
@throws	与 @exception 统一	办法
{@inheritDoc}	从间接父类继承的正文	类、办法
{@link}	插入一个到另外一个主题的链接	类、办法
@param	阐明办法参数	办法
@return	阐明办法返回值	办法
@see	指定一个到另一个主题的链接	类、办法
@since	标记从什么时候引入的	类、办法
@version	指定类的版本	类
{@value}	显示常量的值	须要被 final 润饰

/**
 * 订单服务类
 *
 * @author 陈少平
 * @version 1.0
 */
public interface OrderService {

    /**
     * 订单状态, 示意敞开 {@value}
     *
     * @see OrderType
     */
    int STATUS_CLOSE = 1;

    /**
     * 获取订单号.
     *
     * 订单号生成格局如下
     * <pre>{@code
     * String sn = orderId + RandomUtil.randomLong()
     * }</pre>
     *
     * @param orderId 订单 id
     * @param orderType {@link OrderType}
     * @exception  IOException 读取订单失败
     * @throws NullPointerException 如果 {@code orderId} null.
     * @return {@literal < 订单 ID, 订单号 >}
     *
     * @since 1.2
     * @see OrderType#success
     */
    Map<Long, String> getOrderSn(Long orderId, int orderType) throws IOException;

    /**
     * @deprecated 获取订单状态.
     *
     * @param orderId 订单 id
     * @return 订单状态
     *
     * @since 1.0
     * @see OrderType#success
     * @see OrderType#cancle
     */
    int getStatus(Long orderId);
}

maven 中引入 javadoc 插件

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <configuration>
                <charset>utf-8</charset>
                <encoding>utf-8</encoding>
                <quiet>true</quiet>
                <doclint>none</doclint>
            </configuration>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>