为什么在每个 JavaDoc 行上都有一个星号前缀？答案

【问题标题】：Why an asterisk prefix on every single JavaDoc line?为什么在每个 JavaDoc 行上都有一个星号前缀？
【发布时间】：2016-01-17 07:21:31
【问题描述】：

putting an asterisk before 在 JavaDoc 块中的每一行背后的原因是什么？虽然这似乎是被鼓励和接受的惯例，而且我终于屈服于这样做，但它肯定不会让我的文档编写变得任何更快（尽管有助于创建它们的工具，例如就像 Sublime 中的 DocBlockr plugin）。

多行 cmets 中的行数不超过 75 个字符的一个明显好处是，您的代码可以更轻松地共享，无需对其进行调整，而且查看者无需向右滚动即可阅读您的文档.

但是为什么要更进一步，并有这个额外的约定呢？可以使用可选星号前缀在左侧填充空格...为什么每行？

【问题讨论】：

你的问题听起来更像是一个咆哮而不是一个问题……这个问题没有客观、理性的答案。之所以这样，是因为有人选择这样定义。
我认为这让区块更显眼
可能是古代遗物，很像 80 个字符的行限制。
这部分是咆哮。很高兴知道为什么我必须在我曾经和将要编写的每一行文档上花费额外的按键或三个按键。
@Kayaman 80 个字符的限制不是古代遗物。人们的眼睛和大脑并没有变得更好，只是因为显示器尺寸和分辨率增加了。

标签： java javadoc

【解决方案1】：

这是一种风格约定......尽管 javadoc 命令确实（显然）在某些情况下以不同的方式处理前导 * 和没有前导 * 的情况。

Sun Java Style Guidelines 描述了第 5.2 节中的约定。

为什么？好吧，真正的答案只能由开发 Java 风格指南的人提供。

但是，我的猜测是他们认为它使 javadoc cmets 更加突出。

可以使用可选的星号前缀在左侧填充空格..

Erm ...它是可选的。您不需要遵守约定，除非您的项目风格指南要求您这样做。

很高兴知道为什么我必须在我曾经和将要编写的每一行文档上花费额外的按键或三个按键。

询问开发您正在使用的 IDE 的人 :-)

【讨论】：

【解决方案2】：

我没有什么可以证明这一点，但我总是将其归因于那个时代，当时世界上的一切实际上都是黑色或白色（即黑色或绿色）。在那些时候，您无法轻松地区分代码和 cmets。

这些星号前缀使得识别文件部分变得非常容易，您可以放心地忽略。

【讨论】：

【解决方案3】：

从 Java 1.4 开始，前面的星号是可选的。

您可以省略它们以导出 JavaDoc cmets 中的代码缩进示例。

文档是这样说的：

前导星号 - 当 javadoc 解析文档注释时，前导星号每行上的星号 (*) 字符被丢弃；空格和制表符初始星号 (*) 之前的字符也会被丢弃。从 1.4 开始，如果您在一行中省略了前导星号，则前导空白不再被删除。这使您可以粘贴将代码示例直接写入 <PRE> 标记内的文档注释中，及其缩进将被尊重。空格通常被解释为浏览器比标签更统一。缩进是相对于左边的边距（而不是分隔符/** 或<PRE> 标签）。

http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#leadingasterisks

【讨论】：