在 JavaDoc 中记录 setter/getter、属性和构造函数时，有没有办法避免文档重复？

Question

我真的很喜欢有据可查的代码。但是文档中有很多重复之处，因为基本信息和示例应该可用于属性、setter/getter 和构造函数（另请参阅Simple Getter/Setter comments）。

有没有办法避免 JavaDocs 的重复？我唯一的想法是使用 {@link #function()} 并链接到 JavaDocs 中包含更多信息的部分。

这是一个虚构的例子：

package com.stackoverflow.tests;

/**
 * An Event ...
 */
public class Event {

  /**
   * The date the event takes place.
   * Needs to be in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format.
   * 
   * <h2>Examples:</h2>
   * <ul>
   *   <li>{@code 2016-03-19}</li>
   *   <li>{@code 2016-03-19T05:54:01+00:00}</li>
   *   <li>{@code 2016-W11} - i.e. week 11 of 2016</li>
   * </ul>
   */
  private String date;

  /**
   * Creates an event initializing it with the date and location the event takes place.
   * @param date
   *   Date in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format. Examples:
   *   <ul>
   *     <li>{@code 2016-03-19}</li>
   *     <li>{@code 2016-03-19T05:54:01+00:00}</li>
   *     <li>{@code 2016-W11} - i.e. week 11 of 2016</li>
   *   </ul>
   * @param location
   *   Location ...
   */
  public Event(final String date, final String location) {
    this.date = date;
  }

  /**
   * The date the event takes place.
   * @return
   *   Date in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format.
   */
  public String getDate() {
    return date;
  }

  /**
   * Updates the date the event takes place using an ISO 8601 formatted String.
   * @param date
   *   Date in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format. Examples:
   *   <ul>
   *     <li>{@code 2016-03-19}</li>
   *     <li>{@code 2016-03-19T05:54:01+00:00}</li>
   *     <li>{@code 2016-W11} - i.e. week 11 of 2016</li>
   *   </ul>
   */
  public void setDate(String date) {
    this.date = date;
  }

}

Answer 1

@link 是一个选项，但我更喜欢使用@see 注释：

@see "string"

为字符串添加一个文本条目。没有生成链接。该字符串是书籍或其他对 URL 不可用的信息的引用。 Javadoc 工具通过查找双引号 (") 作为第一个字符来区分这与之前的情况。

@see <a href="URL#value">label</a>

添加由 URL#value 定义的链接。 URL#value 是相对或绝对 URL。 Javadoc 工具通过查找小于号 (

---

我想你会发现这个特别有用，你可以链接到标准的 setter/getter cmets 并避免重复信息。

@see  package.class#member  label

添加一个带有可见文本标签的链接，该链接指向所引用的 Java 语言中指定名称的文档。

Typical forms for @see package.class#member
Referencing a member of the current class
@see  #field
@see  #method(Type, Type,...)
@see  #method(Type argname, Type argname,...)
@see  #constructor(Type, Type,...)
@see  #constructor(Type argname, Type argname,...)

Referencing another class in the current or imported packages
@see  Class#field
@see  Class#method(Type, Type,...)
@see  Class#method(Type argname, Type argname,...)
@see  Class#constructor(Type, Type,...)
@see  Class#constructor(Type argname, Type argname,...)
@see  Class.NestedClass
@see  Class

Referencing an element in another package (fully qualified)
@see  package.Class#field
@see  package.Class#method(Type, Type,...)
@see  package.Class#method(Type argname, Type argname,...)
@see  package.Class#constructor(Type, Type,...)
@see  package.Class#constructor(Type argname, Type argname,...)
@see  package.Class.NestedClass
@see  package.Class
@see  package