目标行 Javadoc

Question

我总是写行内注释，直到我学会了使用 Javadoc。现在我想知道，我怎样才能有效地 select 一行并在 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 和内联注释并不相互排斥。 Javadoc 方法然后在您认为需要的地方在方法中添加内联注释。您通常不会引用方法的 javadoc 中的特定行。

Answer 2

我怀疑是否有任何选项可以提及 javadoc 中的行。这背后的主要原因是因为人们看不到代码，所以如果你在 javadoc 中提到行，除非你能看到代码，否则从文档中看它没有意义。

对于此类行级引用，最好使用内联注释。

Answer 3

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

使用 Javadoc 记录 class 或方法的正确使用，尤其是那些不能自行记录的内容，例如先决条件、后置条件、副作用和异常，包括运行时异常。

Answer 4

你不能（至少不能使用标准标签集）。

首先，@line 不是标准的 javadoc 标签（请参阅下面的标签列表），如果您使用它，您会看到类似以下内容的内容：

sourcefile.java:1234: warning - @line is an unknown tag.

其次，来自关于注释放置的 Oracle 文档（强调我的）：

Documentation comments are recognized only when placed immediately before class, interface, constructor, method, or field declarations -- see the class example, method example, and field example. Documentation comments placed in the body of a method are ignored.

所以，不幸的是，没有办法做到这一点。没有与行相关的标签，也没有办法将javadoc注释放在方法体内。

Oracle's javadoc documentation 中列出了注释的完整语法以及支持的标签列表，特别是：

Commenting the Source Code - 注释语法。
Javadoc Tags - 支持标签的完整列表。

（Java 8 docs for the tool 也有，但没有真正改变，我只是觉得 7 文档更容易浏览。）

此外，哲学上，。

综上所述，您可以根据需要创建自己的 @line 标签，请参阅有关 -tag 和 -taglet 命令行选项 here 的部分（-taglet 就在它的正下方）。也许您之前遇到的 @line 是某人的自定义标签。但是，无论是否自定义标记，您都无法将注释放在方法主体中。

但是要小心...除了不这样做的哲学原因之外，您还必须注意不要在文档中引用绝对行号（无论是自定义标记还是一般情况下） )，因为一旦 add/remove 文件前面的一行，就会破坏所有文档。这将是文档维护的噩梦。

目标行 Javadoc

Target lines Javadoc

java

javadoc

intellij-idea