在 Javadoc 中应该使用哪个标签作为段落分隔符？答案

【问题标题】：Which tag should be used as paragraph separator in Javadoc?在 Javadoc 中应该使用哪个标签作为段落分隔符？
【发布时间】：2011-07-12 17:38:05
【问题描述】：

根据最佳实践，哪个 HTML 标记更适合分解 javadoc 的段落/长部分？

是 还是 ？为什么？

【问题讨论】：

我猜这取决于你对“好”的定义。为什么不同时尝试并检查您的浏览器中的差异？
嗯，我想“很好地展示”是指“遵循最佳实践”。

标签： java comments javadoc

【解决方案1】：

严格来说，自动关闭的 没有意义，因为 应该用于包含一个段落，即该段落应该被 和 包围。

  但是是一个“低级”标签，表示换行符。因此，在语义上正确的表示段落的方法是使用：

<p>This Foo is used to frobincate a {@link Baz}.</p>
<p>It is quite groovy!</p>

对比

This Foo is used to frobincate a {@link Baz}.<br>
It is quite groovy!

从视觉上看， 会在行之间产生更多的空白，而  只会开始一个新行，不会引入任何主要的空白。

【讨论】：

不幸的是 JDK8 禁止自动关闭
，有什么替代方案？
@eckes，您能否参考一下 JDK8 禁止自动关闭的地方
？
@HonzaZidek 您可能知道，JDK8 中对 JavaDoc 的更改影响深远且严格，但没有很好的文档记录。我的“取缔”是指我的观察，只要您不压制它，使用它就会导致构建中止失败：[ERROR] ....java:24: error: self-closing element not allowed [ERROR] * instances. 。我想解决方案是使用 HTML
（就像我习惯使用
作为段落分隔符而不是块级别）。
@eckes：我不知道 JDK8 中 JavaDoc 的变化，如果你能指出一篇文章或文档或任何描述它的东西，我将不胜感激。
这对于一般的 HTML 来说是很好的建议，但实际上对于 Javadocs 来说尤其糟糕。 javadoc 不能很好地适应这些现代最佳实践，并且新版本对接受这样的标记更加严格。

【解决方案2】：

欢迎来到 HTML 3.2。

根据编写doc cmets的官方指南，分隔段落的正确方法是使用段落标签：。看看Format of a Doc Comment 部分中的第七个项目符号。

通常，我强烈建议不要使用这种陈旧过时的做法进行标记。但是，在这种情况下，有充分的理由例外。 Javadoc 工具（除非用自定义 Doclets 彻底更新）会生成旧的、粗糙的、有些损坏的标记。浏览器的构建是为了与当时疯狂的旧标记向后兼容，所以对你来说顺其自然是有意义的。您使用  分隔段落将与 Javadoc 输出的其余部分一致。

【讨论】：

虽然它似乎违反了 HTML 语义，但在您找到的文档中似乎很清楚。
不违反html语义，只违反xhtml语义。
@Wesley：应该链接到使用的文档，带有小写的p。自从您发布答案以来，它可能已经更新。我认为你也应该更新你的答案！
@Lii 在引用 HTML 3.x 元素时，它们以全大写形式指定，例如 。当引用文档中实际编写的文本（无论是 .html 还是 Javadoc）时，您可以根据需要将文本编写和描述为 。

【解决方案3】：

在 Java 8 中，单个起始元素 () 有效。

请注意，javadoc 不喜欢结束元素 ()。

【讨论】：

但是为什么呢？！我在代码中看到了它，这就是为什么我正在阅读这个问题的答案 - 有人离开  没有  ，对其他人来说看起来不错，但对我来说却不是：//
参见 HTML 3.2。 “结束标签是可选的，因为它总是可以被解析器推断出来。”这是一种非常非常古老的做法，过去对许多人来说看起来/看起来都很好。  在网络上并不常见。