5

我正在开发一个用 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。我不知道这是否是一个可以接受的妥协。也许还有其他类似的工具？

4

2 回答 2

12

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

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

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

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

  • 你也可以告诉你的同伴使用更好的编辑器。不，不，我拖钓（：......一点点。

于 2014-09-03T18:48:41.333 回答
2

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

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

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

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

于 2014-12-10T20:56:04.367 回答