没有HTML的Javadocs

Question

Robert C. Martin的书Clean Code包含以下内容：

  

源代码注释中的HTML是令人厌恶的[...]如果某些工具（如Javadoc）将提取注释以​​显示在网页中，那么它应该由该工具负责，而不是程序员，用适当的HTML来装饰评论。

我有点同意 - 如果没有HTML标签，源代码肯定会看起来更干净 - 但是你如何制作看起来不错的Javadoc页面呢？如果不使用HTML标记，就无法分隔段落。 Javadoc manual清楚地说：

  

文档评论是用HTML编写的。

是否有一些可以帮助的预处理工具？ Markdown语法可能是合适的。

Answer 1

我同意。 （这也是我非常反对C＃式“XML评论块”的原因; Javadoc DSL至少为顶级实体提供了一些转义！）。为此，我只是不尝试使javadoc看起来很漂亮......

...无论如何，你可能对Doxygen感兴趣。这是一篇非常快速的帖子Doxygen versus Javadoc。它还提出了你所做的问题： - ）

Answer 2

在“普通”评论中，我不想看到HTML。但对于像JavaDoc这样的工具，HTML增加了添加格式信息，项目符号等的可能性......

我会区分这两件事：

• 非javadoc代码注释适用于维护或增强代码的程序员。他必须挖掘现有的资源，并且任何HTML内容都不会让事情变得更容易。所以，在正常评论中禁止它。
• javadoc-comments用于生成文档。在有帮助的地方使用HTML。但是HTML的一个非常有限的子集就足够了。