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

关键词：

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

【问题讨论】：

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

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

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

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

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

【讨论】：

 标签似乎工作得很好。我要相信这个答案，因为你在论点中给了我弹药（Java 开发人员也使用 ASCII 图）。

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

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

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

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

【讨论】：

用于重写方法的java文档实践，其返回类型是重写方法的返回类型的子类

我正在为一个新的软件包编写Javadoc，我正面临着标题中提到的困境。我有基类方法定义为，classVector<E>{..publicabstractVector<E>add(Vector<E>v);..}最重要的方法定义为，classIntVectorextendsVector<Integer>{..@OverridepublicIntVecto 查看详情

javadoc和注释中的Unicode？

】javadoc和注释中的Unicode？【英文标题】：Unicodeinjavadocandcomments?【发布时间】：2012-05-0822:37:47【问题描述】：一些编译器在JavaDoc和源代码cmets中无法处理非ASCII字符。关于Java源文件中的Unicode，当前（Java7）和未来（Java8及更高版... 查看详情

用idea生成javadoc文档

用IDEA生成javadoc文档打开相应的选项面板设置-encoding是java代码编码，-charset是对生成文档所用的编码。-windowtitle就是对应html的<title>标签1-encodingUTF-8 -charsetUTF-8 -windowtitle "test"结果  查看详情

新的 javadoc 注解 @apiNote

】新的javadoc注解@apiNote【英文标题】：Newjavadocannotation@apiNote【发布时间】：2014-05-0514:07:35【问题描述】：我在LongStream类文档中发现了一个新的且未记录的javadoc标记。javadoc标签@apiNote似乎是用来详细解释某个方法的，但是没有关... 查看详情

intellijidea如何生成javadoc？

javadoc基本介绍javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同... 查看详情

将 javadoc 用于 Python 文档 [关闭]

】将javadoc用于Python文档[关闭]【英文标题】：UsingjavadocforPythondocumentation[closed]【发布时间】：2011-07-1702:41:56【问题描述】：我目前从Python开始，我有很强的PHP背景，在PHP中我习惯使用javadoc作为文档模板。我想知道javadoc是否在Pyth... 查看详情

intellijidea中如何使用javadoc

javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的... 查看详情

读书笔记|《修改软件的艺术》

最近读了《修改软件的艺术》一书，这本书讲述了作者对关于如何写比较容易维护代码的的经验，并把他们整理成了9条实践方式。它们分别是实践1：在问如何做之前先问做什么、为什么做、给谁做实践2：小批次... 查看详情

在 C++ 中创建同时支持 Unicode 和 ASCII 的库的最佳实践是啥？

】在C++中创建同时支持Unicode和ASCII的库的最佳实践是啥？【英文标题】：WhatisthebestpracticeforcreatinglibrariesthatsupportbothUnicodeandASCIIinC++?在C++中创建同时支持Unicode和ASCII的库的最佳实践是什么？【发布时间】：2009-09-3017:59:13【问题描... 查看详情

javadoc注释规范

Javadoc虽然是Sun公司为Java文档自动生成设计的，可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。但是Javadoc的注释也符合C的注释格式，而且doxyen也支持该种风格的注释。官方文档：http://docs.or... 查看详情

javadoc学习

JavaDoc学习javadoc命令是用来生成自己的API文档的常用的参数信息@author作者名@version版本号@since指明需要最早使用的jdk版本@return返回值情况@param参数名@throws异常抛出情况Overview(JavaPlatformSE8)(oracle.com)生成注释文档javadoc-djavadoc-encoding... 查看详情

c语言数字图像处理进阶---17流行艺术风滤镜

流行艺术风滤镜(PopArt)        谓部流行艺术风滤镜，是这样一款特效：                  原图 &nb 查看详情

c语言数字图像处理进阶---17流行艺术风滤镜

流行艺术风滤镜(PopArt)        谓部流行艺术风滤镜，是这样一款特效：                  原图 &nb 查看详情

@java开发者，springboot最流行的16条实践解读！

SpringBoot是最流行的用于开发微服务的Java框架。在本文中，我将与你分享自2016年以来我在专业开发中使用SpringBoot所采用的最佳实践。这些内容是基于我的个人经验和一些熟知的SpringBoot专家的文章。在本文中，我将重点介绍SpringB... 查看详情

Python：从文本文件打印 ascii 艺术，反斜杠加倍

】Python：从文本文件打印ascii艺术，反斜杠加倍【英文标题】：Python:printingasciiartfromtextfile,backslashesarebeingdoubled【发布时间】：2018-03-0503:58:00【问题描述】：我在记事本中制作了一些ascii艺术作品，将其保存为.txt文件，然后我使... 查看详情

将花哨/艺术 unicode 文本转换为 ASCII

】将花哨/艺术unicode文本转换为ASCII【英文标题】：Convertfancy/artisticunicodetexttoASCII【发布时间】：2021-11-2810:04:10【问题描述】：我有一个unicode字符串，例如“??????????????????????????????????”并想将其转换为ASCII形式的“暴徒生活”。... 查看详情

生成javadoc文档

JavaDoc是一种将注释生成HTML文档的技术，生成的HTML文档类似于Java的API，易读且清晰明了。在简略介绍JavaDoc写法之后，再看一下在IntellijIdea中如何将代码中的注释生成HTML文档。java中的注释有三种：单行注释：在IDEA中快捷键为Ctrl... 查看详情

eclipse怎样生成javadoc

如题使用eclipse生成文档（javadoc）主要有三种方法：1，在项目列表中按右键，选择Export（导出），然后在Export(导出)对话框中选择java下的javadoc，提交到下一步。在JavadocGeneration对话框中有两个地方要注意的：javadoccommand:应该选择... 查看详情