目标行Javadoc

Question

在学习使用Javadoc之前，我总是写内联注释。现在，我想知道，我如何能够有效地选择路线，并告诉一些关于它的Javadoc，而不是内部注释。

示例：
这是我的空白：

public void test() {
    //This is a test sentence
    String testSentence = "Test";
    //This is another test sentence
    String anotherTestSentence = "Test";
}

如果没有其他（更有效的）方法，我该怎么做：

/**
 * @line 2 This is a test sentence
 * @line 3 This is another test sentence
 */
public void test() {
    String testSentence = "Test";
    String anotherTestSentence = "Test";
}

有谁知道是否确实有更好的方法，还是应该使用内联注释而不是Javadoc？我注意到@line做了一些奇怪的事情，但是我找不到任何东西。

Answer 1

Javadoc旨在记录API，而不是实现。您应该避免在Javadoc中指定实现细节，因为这样做会限制您更改实现的能力。调用者可能开始依赖于您记录的实现细节。

使用Javadoc来记录对类或方法的正确使用，尤其是那些非自记录的东西，例如前提条件，后置条件，副作用和异常，包括运行时异常。