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工具通过查找双引号（＆＃34;）作为第一个字符来区别于此前的情况。

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

添加URL＃value定义的链接。 URL＃值是相对或绝对URL。 Javadoc工具通过查找小于号（＆lt;）作为第一个字符来区别于其他情况。

我认为你会发现这个特别有用，你可以链接到标准的setter / getters注释并避免重复的信息。

@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

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

1 个答案: