什么是ASCII-art文档的流行JavaDoc实践？

Question

我正在开发一个用Java编写的项目，旨在通过一个严格定义消息字段位位置的消息系统来传输数据。这意味着我们有一个完整的字典类库，旨在将对象输入数据移位到消息二进制表示或从消息二进制表示移位。这个库相当大，而且由于协议还很年轻，每年都有调整和改变的倾向。

此库的JavaDoc提供了ASCII艺术表和图表，用于解释特定方法所期望的输入（或输出）。这些表格非常重要，因为查找文档并验证该方法实际上是否符合文档所说的内容可能非常耗时，容易出错。使用单个简单的ASCII位表示移位可以使这更容易。

我有一位同事坚持认为ASCII艺术不属于JavaDoc（即使是标签），而且我们将Eclipse配置为在保存时自动格式化代码。他提供了两种重新格式化文档的方法：

1. 嵌入图片。
2. 使用HTML表格。

图像没问题，除了Eclipse不渲染SVG图像。我完全不能接受的是，我们维护一个SVG图像，然后将图像作为PNG导出到我们的文档仓库，然后将PNG与HTML链接起来。这种情况下涉及的维护量似乎完全疯了。谁负责确保所有PNG，SVG和代码同步？此外，显然，没有图像，数据将无法读取。

HTML表格选项不好有两个原因。首先，Eclipse格式化程序将每个标记和值放在它自己的行上，这意味着每个值占用三行。它在源代码中留下了巨大的空白，并且在不呈现HTML的情况下完全不可读。更糟糕的是，我们的一些表格很复杂，对于那些已经拒绝创建文档的开发人员来说，对HTML表格进行故障排除并不是我负责任的事情。

因此，如果我的同事关于“java人”不使用ASCII图表进行文档化是正确的，那么什么是标准的行业实践，为我们提供了保存这些图表的方法？与使用ASCII图标签相比，这种方法有何益处？如果您能够回答为什么JavaDoc没有发展为提供可读标记而不是依赖HTML，那么奖励积分。

---

修改：我刚刚找到markdown-doclet。我不知道这是否是一个可以接受的妥协。也许还有其他类似的工具？

Answer 1

一个老问题，但我有类似的挫折。

• 您可以使用/*-构造来阻止Eclipse格式化给定的注释。请参阅：https://stackoverflow.com/a/5466173。

• 使用{@code}构造和/或<pre>。见：https://stackoverflow.com/a/542142。我想，一般反对ASCII图的人也会反对这些。但也许它已被载入Javadoc语法将是对你有利的一点。

• 指出即使Java开发人员在适当的地方使用ASCII diagrams。

• 您也可以告诉您的同事使用better editor。不，不，我很棒（：......一点点。

Answer 2

在公司，我们已经根据已经提出的主要原因决定使用ASCII图，我们相信它们足以证明这一选择：

1. 维护成本和可行性。
   我见过外部资源过时的项目...... 几乎是不可避免的。
2. 随处显示（IDE，文本编辑器）。
   我们不为内部项目生成Javadoc并将它们放在Web服务器上。发展习惯已发生变化......见http://www.flowstopper.org/2014/12/graphical-visualizations-in-javadoc.html

ASCII图也迫使人们保持简单，这通常有助于清晰。

我发现http://www.asciidraw.com/是一个很好的工具。