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来记录类或方法的正确使用，尤其是非自我记录的事情，例如前置条件，后置条件，副作用和异常，包括运行时异常。

Answer 2

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

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

Answer 3

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

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

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

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

文档注释仅在紧接在类，接口，构造函数，方法或字段声明之前放置时才会被识别 - 请参阅类示例，方法示例和字段示例。 忽略方法正文中的文档注释。

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

Oracle's javadoc documentation列出了评论的完整语法以及支持的标记列表，特别是：

Commenting the Source Code - 评论语法。
Javadoc Tags - 支持的代码的完整列表。

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

此外，哲学上，Kevin Krumwiede hits the nail on the head。

如果您愿意，可以创建自己的@line标记，请参阅-tag和-taglet命令行选项here（{{1}就在它下面）。也许您以前与-taglet的遭遇是某人的自定义标记。是否自定义标记，您将无法将注释放在方法体本身中。

要小心，但是......除了不这样做的哲学原因之外，你还必须注意不要在你的文档中引用绝对行号（无论是自定义标签还是一般），因为一旦在文件中添加/删除一行，您就会中断所有文档。这将是文档维护的噩梦。

Answer 4

Javadoc和内联注释不是互斥的。 Javadoc方法然后在您认为需要的方法中添加内联注释。您通常不会在方法的javadocs中引用特定行。

目标行Javadoc

4 个答案: