将方法参数与 JavaDoc 中的 class 成员链接

Question

在我们公司，有一条严格的规定，就是凡事都要评论。该规则有一些弱点，例如重复文本。为了避免重复注释，我想将方法参数引用到 class 成员，但找不到合适的解决方案。

当我link方法参数中的class成员并将方法参数悬停时，

  /**
   * I would like to see this comment
   */
  private int       lineNumber;

  /**
   * Creates a new {@link GroupByMetaData} object.
   *
   * @param aLineNumber {@link GroupByMetaData#lineNumber}
   */
  public GroupByMetaData( int aLineNumber )
  {
    super();
    this.lineNumber = aLineNumber;
  }

结果如下；

实现这一目标的正确方法是什么？

Answer 1

无法将一个项目的 javadoc 复制到另一个项目中，除了 {@inheritDoc} 只能从同一项目的超级 class 文档中插入。

构造函数设置私有 int 字段这一事实是内部实现的一部分。您的 javadoc 不应提及或 {@link} 私有字段；相反，javadoc 应该从概念上描述它。

私有 javadoc 通常与 public javadoc 不同。私有 javadoc 将包含 class 的普通用户不应看到的重要实现细节。例如：

/**
 * Line of input this object will analyze.  This is never negative.
 * Controls the loops in the `read` method and the `translate` method.
 */
private int lineNumber;

将方法参数与 JavaDoc 中的 class 成员链接

Linking method parameter with a class member in JavaDoc

java

javadoc