ASCII艺术文档的流行JavaDoc实践是什么？

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

这个库的JavaDoc提供了ASCII art表和图表，解释了特定方法作为输入（或输出）的期望值。这些表非常重要，因为查找文档和验证方法是否确实执行了文档中所述的操作可能非常耗时，而且容易出错。遵循位移位的单一、简单的ASCII表示法使这变得容易得多

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

嵌入图像

使用HTML表格

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

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

所以，如果我的同事关于“java人”不使用ASCII图表作为文档的说法是正确的，那么什么是标准的行业实践，为我们提供了保存这些图表的方法？与使用带有ASCII图表的标记相比，这种方法有什么好处？如果您能够回答为什么JavaDoc没有演变为提供可读标记，而不是依赖HTML，那么您将获得额外的积分

---

---

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

这是一个老问题，但我也遇到过类似的挫折

• 您可以使用

  /*-

  构造来防止Eclipse格式化给定的注释。请参阅：

• 使用

  {@code}

  构造和/或
  。请参阅：。我想一般反对ASCII图的人也会反对这些。但也许它已经被载入Javadoc语法中，这会对您有利

• 指出，即使是Java开发人员也在适当的地方使用

• 你也可以告诉你的同伴使用。不，不，我是巨魔（：…有点

---

在该公司，我们决定使用ASCII图表，原因已经给出，我们相信它们足以证明我们的选择：

维护成本和可行性。
我见过外部资源过时的项目……这几乎是不可避免的

显示在任何位置（IDE、文本编辑器）。
我们不会为内部项目生成Javadoc并将其放在web服务器上。开发习惯已经改变…请参阅

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

---

我发现这是一个很好的工具。

Java和Javadoc于1996年首次发布，它们早于Markdown（2004年）。当然，这并不意味着它们不能为可读表和其他标记引入机制。“保存时的格式代码”这是一件非常好的事情，因为它可以确保您可以在任何时候重新格式化，而不会导致提交日志爆炸。如果我们使用Vim，我会非常高兴。但是标记似乎工作得很好。我相信这个答案，因为您在争论中给了我弹药（Java开发人员也使用ASCII图）。在这里使用Intellij，

对我来说很有用。没有理由不使用ascii图表，只要它们遵循您对其他任何内容的指导原则；保持清晰和简洁。我认为图表实际上比必须键入所有内容更清晰。