JDK 社区，正在调查在Java 文档中加入Markdown支持

正如一些人已经注意到的，我们正在调查在Java文档注释中支持Markdown的可能性。

在Java文档注释中支持Markdown。

我们为什么要这样做？ 这已经是一个非正式的要求了，因为这已经是一个非正式的要求了，自从Markdown作为一种流行的编写格式出现以来，我们正在做这件事的原因与作者喜欢在独立文档中使用Markdown而不是原始的在独立的文档中使用Markdown而不是原始的HTML。特别是，使用原始的HTML有点儿对于简单的格式化任务，比如字体的改变，使用原始的HTML有些笨重和视觉上的干扰性。

列表和表格，这在API文档中是经常需要的。

需要解决哪些挑战？ 有两个主要的挑战需要解决有两个主要的挑战需要解决：哪个版本的Markdown，以及如何在文档注释中加入使用Markdown的能力？

Markdown在文档注释中的能力？

从一开始，Markdown就因为有困难的实现而受到影响。

没有一个共同的规范，而且常常有一些不同的行为。这个问题 这个问题由于多个不同的扩展的引入而变得更加严重。

都是为了提供原始版本不支持的额外功能。

版本不支持的功能。这个问题由于CommonMark的兴起而得到了一定程度的改善。

它的目的是为Markdown提供一个更正式的规范，并且采用了CommonMark（尽管经常有一些扩展）在一些流行的社交平台上被采用。

就在文档注释中使用Markdown而言，我们并不希望替换对现有内联标签（如`{@link

...}`）或块状标签（如`@param`,`@return`,和`@throws`），其中大部分都没有在基本的Markdown中没有相应的标签。(一个明显的标签有一个替换的一个明显的标签是在代码跨度中使用反斜线，而不是`{@code ...}`）。

将所有现有标签的使用以及提供用户定义的标签的能力替换成提供用户定义的标签的能力，所以我们只能用Markdown扩展来代替想在文档注释中适应标准和用户定义的标签的使用。

Markdown在文档注释中的使用。一个稍微不同的说法是我们希望支持在文档注释中使用Markdown结构

今天，在任何可以在文档注释中使用原始HTML的地方。

Markdown并不是HTML。虽然它确实能容纳适当的HTML的使用元素，但Markdown对一些其他普通文本的解释是不同的。 最值得注意的是它对空白字符的解释。一般来说，空白处在HTML中并不重要（除了在`

`元素中），但在Markdown中，一个空行被解释为一个段落。
空白行被解释为一个段落中断。这本身就足以说明我们不能在任何地方默认启用Markdown，无论是对新的还是现有的文档注释。 这意味着我们需要同时支持传统的的注释（这些注释不是在考虑到Markdown的情况下写的），以及使用Markdown的注释。
使用Markdown的能力。 在这个异质性的世界里，我们需要能够能够从可能使用混合注释格式的代码中生成API文档。
格式的代码生成API文档。值得注意的是，`{@inheritDoc}`标签能够引用不同类的文本在不同的类中，甚至可能在不同的项目中。 比如说。
一个提供自定义集合的项目（例如，像Guava），可能想要继承Java SE中核心集合类的文档。 
Markdown 并非没有问题。它采用“如果它是不是有效的句法结构，它必须是文字文本”。在任何情况下都不会报告错误。如果输入看起来像是 HTML，它会被传递给输出，如果不是，它可能会被 HTML 验证器捕获到下游实际上有效的 HTML，如果作者选择运行这样的工具。如果输入包含有拼写错误的 HTML（例如属性值缺少引号），Markdown 会将输入的该片段视为文字文本，并生成适合该文字文本的 HTML。在这种情况下，错误的输入将_not_ 被下游 HTML 验证器捕获，如果没有被捕获 校对输出，错误的输入将使其一路“清晰” 到生成的输出。鉴于作者不_校对他们生成的文档的经验证据，你有增加的风险生成的输出中的问题。
为什么这是错误处理问题而不是其他情况下的问题？在在其他情况下，Markdown 通常是一次性编写的和/或有些短暂的。
而且，“预览”渲染输出的延迟通常非常低，要么使用明确的“预览”按钮，要么使用“实时预览”
键入时更新。如果您可以访问带有实时预览功能的 Markdown 编辑器，尝试输入类似`example` 的字符串，看看它是如何实现的以未完成状态预览，然后以最终状态预览。所以，无论你正在输入某种设计文档，或者 Github 上的提交消息，它是
通常很容易验证渲染是否符合预期。相比之下，文档注释可能会长期存在，只要 API本身被维护，并且可能由不同的作者编辑或更新时间，使用不同的工具。并运行 javadoc 来生成 API文档可能被视为事后的想法，在开发和调试底层API的实现。如果我们可以的话会有所帮助减少查看文档评论的呈现形式的延迟，要么带有“预览”按钮或“实时预览”，虽然这可能超出范围就一个项目而言，定义使用 Markdown 的能力，我们至少可以以可能增加创作工具采用率的方式定义功能。
看工具，`javadoc` 不是唯一处理文档的工具注释。与 IDE 和其他创作工具一样，`jshell` 还提供了显示文档注释的能力。也许比 javadoc 本身更重要的是，jshell 可能会被要求显示“传统”注释，因为不使用 Markdown 注释或处理 Markdown 的文件或库评论，用于使用它们的文件或库。再次，我们需要考虑设计生态系统中其他工具的需求和影响新功能，例如在文档注释中支持 Markdown。
——乔恩