什么是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图.

• 您也可以告诉您的同事使用更好的编辑器.不,不,我是巨魔(:......一点点.