从 java 中的文档评论访问私有字段

Question

给出以下 class：

public class A {
    private Boolean attribute;
     
    public Boolean getAttribute () {
        return this.attribute; 
    }    
    
    public Boolean setAttribute (Boolean b) {
        this.attribute = b; 
    }
}

我如何通过以下方式从另一个 class 的文档注释中访问 class A 的私有字段，以指定该字段在记录的方法，即使不是直接访问？

public class B {
    /**
     * This method turns the {@link A#attribute} attribute to false.
     */
    public turnOffField (A a) {
        //...
    }
}

上面的{@link A#attribute}只是一种表示，因为正如您想象的那样，它不起作用。

注意：在我的例子中，文档注释的目的不是生成 javadocs 页面，而是用作内部文档，仅供开发人员使用。所以在这种情况下，-produce 等命令行选项不能满足目的。

Answer 1

Javadoc 页面旨在供开发人员使用，且仅供开发人员使用。此外，请始终记住，您也可以通过基本评论与未来的开发人员进行交流。毕竟javadoc只是一种特殊的注释形式

在这个特定的用例中，我建议修改开发人员文档的形式。

让我们举个例子，因为我喜欢从大框架中复制，让它成为 Java

LinkedList<String> list = new LinkedList<>();
list.add("Hello");
list.add("World");

让我们看一下 add 方法的第二次调用。在内部，此方法创建一个新的 LinkedList.Node 包装器并将列表的内部 tail 成员设置为该包装器（并执行一些其他操作）。

我们真的关心这些细节吗？我想这是非常罕见的，在大多数情况下，我们唯一感兴趣的是 "World" 被添加到列表中，无论实现必须做什么才能实现这一点。

要以相同的方式正确记录问题中给出的示例，我们需要知道 attribute 如何影响 A 的行为。假设它控制一些跟踪，那么我们可以记录

class A {

    private boolean attribute;

    /**
     * Controls tracing of this instance.
     */
    public boolean setAttribute(boolean attribute) {
        this.attribute = attribute;
    }

}

和

class B {

    /**
     * Turns of tracing for the specified instance of {@code A}.
     * @see A#setAttribute
     */
    public void turnOffTracing(A a) {
        a.setAttribute(false);
    }

}

一般来说，您不需要引用内部成员来描述您的 class 或方法的工作原理。这将打破 private 字段的基本思想，因为它的合同在某种程度上不再是私有的 - 如果您更改该字段，您的 class 的文档也需要更改，因此一些客户可能也想更改他们的代码。

当然在这个例子中重命名setAttribute也是一个好主意，但这并不影响文档的措辞。

从 java 中的文档评论访问私有字段

Acces private field from doc comment in java

java

spring-boot

documentation

javadoc

private