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

Posted 2023-02-21

【中文标题】在 Javadoc 中应该使用哪个标签作为段落分隔符？

【英文标题】：Which tag should be used as paragraph separator in Javadoc?

【发布时间】：2011-07-12 17:38:05

【问题描述】：

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

是<p /> 还是<br />？为什么？

【问题讨论】：

我猜这取决于你对“好”的定义。为什么不同时尝试并检查您的浏览器中的差异？

嗯，我想“很好地展示”是指“遵循最佳实践”。

【参考方案1】：

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

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

<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!

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

【讨论】：

不幸的是 JDK8 禁止自动关闭 ，有什么替代方案？

@eckes，您能否参考一下 JDK8 禁止自动关闭的地方？

@HonzaZidek 您可能知道，JDK8 中对 JavaDoc 的更改影响深远且严格，但没有很好的文档记录。我的“取缔”是指我的观察，只要您不压制它，使用它就会导致构建中止失败：[ERROR] ....java:24: error: self-closing element not allowed [ERROR] * instances.<br/>。我想解决方案是使用 HTML （就像我习惯使用

@eckes：我不知道 JDK8 中 JavaDoc 的变化，如果你能指出一篇文章或文档或任何描述它的东西，我将不胜感激。

这对于一般的 HTML 来说是很好的建议，但实际上对于 Javadocs 来说尤其糟糕。 javadoc 不能很好地适应这些现代最佳实践，并且新版本对接受这样的标记更加严格。

【参考方案2】：

欢迎来到 HTML 3.2。

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

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

【讨论】：

虽然它似乎违反了 HTML 语义，但在您找到的文档中似乎很清楚。

不违反html语义，只违反xhtml语义。

@Wesley：应该链接到使用<p>的文档，带有小写的p。自从您发布答案以来，它可能已经更新。我认为你也应该更新你的答案！

@Lii 在引用 HTML 3.x 元素时，它们以全大写形式指定，例如 <P>。当引用文档中实际编写的文本（无论是 .html 还是 Javadoc）时，您可以根据需要将文本编写和描述为 <p>。

【参考方案3】：

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

请注意，javadoc 不喜欢结束元素 (</p>)。

【讨论】：

但是为什么呢？！我在代码中看到了它，这就是为什么我正在阅读这个问题的答案 - 有人离开 <p> 没有 </p> ，对其他人来说看起来不错，但对我来说却不是：//

参见 HTML 3.2。 “结束标签是可选的，因为它总是可以被解析器推断出来。”这是一种非常非常古老的做法，过去对许多人来说看起来/看起来都很好。 </p> 在网络上并不常见。