利用@see、@link增强程序可读性

诸多原因，我们的程序往往解释不了它自己。

即使程序可以解释自己，那么，谁会用它？它跟谁有关系？  这些就用到javadoc中的@see、@link了。这两个注解实现在javadoc注释里链接代码，方便我们追溯程序。

经常看java源码的同学可能注意到了，java源码里有很多的@see、@link，来辅助我们查阅。

比如下面spring-data-redis.jar中org.springframework.data.redis.core.ValueOperations<K, V>#setIfAbsent

    /**
     * Set {@code key} to hold the string {@code value} and expiration {@code timeout} if {@code key} is absent.
     *
     * @param key must not be {@literal null}.
     * @param value must not be {@literal null}.
     * @param timeout the key expiration timeout.
     * @param unit must not be {@literal null}.
     * @return {@literal null} when used in pipeline / transaction.
     * @since 2.1
     * @see <a href="http://redis.io/commands/set">Redis Documentation: SET</a>
     */
    @Nullable
    Boolean setIfAbsent(K key, V value, long timeout, TimeUnit unit);

调用这个方法的地方就可以看到其javadoc注释。

 

 再例如rt.jar包里 java.math.BigDecimal#equals方法的javadoc，其中有{@link #compareTo(BigDecimal) compareTo}，有@see

    /**
     * Compares this {@code BigDecimal} with the specified
     * {@code Object} for equality.  Unlike {@link
     * #compareTo(BigDecimal) compareTo}, this method considers two
     * {@code BigDecimal} objects equal only if they are equal in
     * value and scale (thus 2.0 is not equal to 2.00 when compared by
     * this method).
     *
     * @param  x {@code Object} to which this {@code BigDecimal} is
     *         to be compared.
     * @return {@code true} if and only if the specified {@code Object} is a
     *         {@code BigDecimal} whose value and scale are equal to this
     *         {@code BigDecimal}'s.
     * @see    #compareTo(java.math.BigDecimal)
     * @see    #hashCode
     */
    @Override
    public boolean equals(Object x) {

 

 

 

	用途	相同点	不同点
@see		@see com.....XXXClass @see com.....XXXClass#XXXMethod @see <a href="url">url</a>	与注释文本是分开的，要另起一行写
@link		{@link com.....XXXClass [可选标题]} {@link com.....XXXClass#XXXMethod [可选标题]}	使用在注释文字里，要包在{}里

 

 

 

使用@see为class添加注释

/**
 * 企业开票申请单的状态枚举
 * @see com.emax.zhenghe.rpcapi.modules.bill.vo.EnterpriseInvoiceApplyVO#billStatus
 * @author zhangguozhan
 * @date 2021-5-20 17:56
 * @note 指毛病易，列优点难。区别在于，一个是本能，一个是能力。
 */
@Getter
@AllArgsConstructor
public enum InvoiceApplyStatusEnum {
    。。。
}

 效果：

 

 

/**
 * 基于MDC+Filter的跨应用分布式日志追踪解决方案
 *
 * @see <a href="https://www.cnblogs.com/iwangjie/p/14811865.html">基于SLF4J的MDC机制和Dubbo的Filter机制，实现分布式系统的日志全链路追踪</a>
 */
@Slf4j
@Activate(order = 999, group = {Constants.PROVIDER_PROTOCOL, Constants.CONSUMER_PROTOCOL})
public class DubboTraceFilter implements Filter {
    ...

 

 

使用@link为class的成员属性添加注释

public class EnterpriseOnlineAuthVO {
    
    。。。
    
    /**
     * 子商户类型，参见{@link com.emax.channel.base.enums.PlatformMerchantEnum}
     */private String merchantType;
    
    。。。
    
}

效果：

 

使用@see为class的成员属性添加注释

public class EnterpriseOnlineAuthVO {
    
    。。。
    
    /**
     * 子商户类型
     * @see com.emax.channel.base.enums.PlatformMerchantEnum
     */
    private String merchantType;
    
    。。。
    
}

效果：