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

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

即使程序可以解释自己，那么，谁会用它？它跟谁有关系？  这些就用到了@see、@link了。

经常看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注释。

	用途	相同点	不同点
@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 {
    。。。
}

 效果：

使用@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;
    
    。。。
    
}

效果：