没有HTML的Javadocs

Question

罗伯特·C·马丁(RobertC.Martin)的书“清洁代码”包含以下内容：

源代码注释中的HTML是一个令人憎恶的..。如果某个工具(如Javadoc)要提取注释以显示在Web页面中，那么应该由该工具而不是程序员负责用适当的HTML来修饰注释。

我有点同意--如果没有HTML标签，源代码看起来肯定会更干净--但是你是如何制作好看的Javadoc页面的呢？如果不使用HTML标记，甚至无法将段落分开。Javadoc手册说得很清楚：

文档注释是用HTML编写的。

这里有一些预处理工具可以帮助吗？降价语法可能是合适的。

Answer 1

我同意。(这也是我强烈反对C#风格的"XML注释块“的原因；Javadoc DSL至少为顶级实体提供了一些逃避！)为此，我根本不想让javadoc看起来很漂亮.

...anyway，你可能对氧气感兴趣。这是一个非常快速的帖子DO2与Javadoc。它还提出了您所做的问题:-)

Answer 2

HTML不是我想在“普通”注释中看到的东西。但是对于像JavaDoc这样的工具，HTML增加了添加格式化信息、项目点等的可能性.

我要区分这两件事：

• 非javadoc代码注释是为维护或增强我所质疑的代码的程序员准备的。他必须挖掘现有的源代码，而coments中的任何HTML都不能使事情变得更容易。所以，禁止在正常的评论。
• javadoc-注释用于生成文档。在有帮助的地方使用HTML。但是一个非常有限的HTML子集就足够了。