ASCII 艺术文档的流行 JavaDoc 实践是啥？ [关闭]

Posted 2023-03-05

【中文标题】ASCII 艺术文档的流行 JavaDoc 实践是啥？ [关闭]

【英文标题】：What is a popular JavaDoc practice for ASCII-art documentation? [closed]ASCII 艺术文档的流行 JavaDoc 实践是什么？ [关闭]

【发布时间】：2014-02-05 20:03:32

【问题描述】：

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

此库的 JavaDoc 提供了 ASCII 艺术表和图表，用于解释特定方法期望作为输入（或输出）的内容。这些表格非常重要，因为查找文档并验证该方法是否确实按照文档中的说明进行操作可能会耗费大量时间并且容易出错。使用单一的、简单的 ASCII 表示的位移会使这变得容易得多。

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

嵌入图像。 使用 html 表格。

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

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

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

---

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

【问题讨论】：

Java 和 Javadoc 于 1996 年首次发布，早于 Markdown (2004)。

当然，但这并不意味着他们不能引入可读表和其他标记的机制。

“保存时格式化代码”是一件非常好的事情，因为它确保您可以随时重新格式化而不会导致提交日志爆炸。

【参考方案1】：

一个老问题，但我也有类似的挫败感。

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

使用@code 构造和/或<pre>。请参阅：https://***.com/a/542142。我想一般反对 ASCII 图的人也会反对这些。但也许它已被载入 Javadoc 语法，这对您有利。

指出即使是 Java 开发人员也会在适当的时候使用ASCII diagrams。

你也可以告诉你的伙伴使用better editor。不，不，我是巨魔（：......一点点。

【讨论】：

如果我们使用 Vim，我会很高兴。但是

在这里使用 Intellij，<pre></pre> 对我有用。没有理由不使用 ascii 图，只要它们遵循您对其他任何事情的指导方针；保持简洁明了。我会争辩说，图表实际上会使很多文档比必须输入所有内容更清晰。

【参考方案2】：

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

维护成本和可行性。 我见过外部资源过时的项目...这几乎是不可避免的。 显示在任何地方（IDE、文本编辑器）。 我们不会为内部项目生成 Javadoc 并将它们放在 Web 服务器上。开发习惯变了……见http://www.flowstopper.org/2014/12/graphical-visualizations-in-javadoc.html

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

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