继http://asciidoctor.org/news/2014/08/12/asciidoctor-1-5-0-released/[Asciidoctor 1.5.0]和http://asciidoctor.org/news/2014/08/21/asciidoctorj-1-5-0-released/[AsciidoctorJ 1.5.0]的发布之后，https://github.com/asciidoctor/asciidoclet/[Asciidoclet]的1.5.0版本已经发布，包含了几个重要的新功能，包括一个全新的外观和感觉！

Asciidoclet是什么？

Asciidoclet允许Java开发者使用可移植且丰富的http://asciidoctor.org/docs/what-is-asciidoc/[AsciiDoc]语法来编写Javadoc注释，而非HTML。

简而言之，为什么要像这样写混乱的Javadoc呢？

/**
 * This class has the following features:
 * <ul>
 *   <li>Support for <strong>foo</strong></li>
 *   <li>Support for bar</li>
 * </ul>
 */
public class Thing implements Something { ... }

当你可以像这样编写整洁的Javadoc时！

/**
 * This class has the following features:
 *
 * - Support for *foo*
 * - Support for bar
 */
public class Thing implements Something { ... }

好多了！现在源代码中的注释更容易阅读和编写，并且可以在Javadoc之外重用。最重要的是，Javadoc生成的HTML还是看起来棒极了（可能甚至更好）。

当然，这个例子仅仅触及皮毛。通过轻量级AsciiDoc语法可以使用表格、列表、带语法高亮的代码示例、链接、包含以及http://asciidoctor.org/[Asciidoctor]的所有功能。

现在，开发者可以专注于_内容_而不是_格式_，并且仍然获得一个美观的最终成果。

文物信息

制品信息（jCenter @ Bintray）
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

1.5.0

pom jar javadoc (jar) sources (jar)
工件信息（Maven 中央仓库）
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

1.5.0

pom jar javadoc (jar) sources (jar)

安装中

在Maven中，只需将Asciidoclet doclet的名称和工件添加到`maven-javadoc-plugin`声明中：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.9</version>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <doclet>org.asciidoctor.Asciidoclet</doclet>
    <docletArtifact>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoclet</artifactId>
      <version>1.5.0</version>
    </docletArtifact>
  </configuration>
</plugin>

查看Asciidoclet指南，了解适用于其他构建系统的示例以及所有可用的doclet选项。

发布亮点

基于Asciidoctor 1.5.0构建

Asciidoclet继承了来自http://asciidoctor.org/news/2014/08/12/asciidoctor-1-5-0-released/[Asciidoctor 1.5.0]和http://asciidoctor.org/news/2014/08/21/asciidoctorj-1-5-0-released/[AsciidoctorJ 1.5.0]的所有改进。

Important
 Asciidoctor 1.5.0 引入了一些语法变更。请参阅http://asciidoctor.org/docs/migration/[迁移指南]以了解如何迁移您的内容的详细信息。

改进的样式表

Asciidoclet包含一个默认的样式表，其中包含来自Asciidoctor 1.5.0的样式。这意味着在Javadoc中的AsciiDoc内容会以类似于在其他环境中使用Asciidoctor时的外观和感觉进行渲染。

Javadoc输出
Figure 1. 使用Java 8派生样式表的示例Javadoc
Note

Javadoc的HTML输出会随着Java平台的不同版本而变化，因此Asciidoclet会根据其运行的Java版本选择合适的样式表：

  • 对于Java 7和Java 8，使用基于默认Java 8 Javadoc样式表的样式表。

  • 对于Java 5和6，样式表是基于Java 6 Javadoc样式表的。

如果你想使用自己的样式表，你仍然可以通过使用Javadoc的`-stylesheetfile`选项来实现。

AsciiDoc概述文件

Javadoc的`-overview`选项允许你指定一个HTML文件，该文件用作生成文档中的概述或索引页面。这对于大型项目特别有用，概述可以为用户提供有用的介绍，并帮助他们导航API。

Asciidoclet现在也支持用AsciiDoc编写的概述文件，完全支持AsciiDoc的功能，如包含和文档属性。以[x-].adoc、*.ad、*.asciidoc`或[x-].txt`命名的概述文件将由Asciidoclet处理。其他文件被假设为HTML，并将由Javadoc的标准文档工具处理。

文档属性

Asciidoclet 现在完全支持 Asciidoctor 的http://asciidoctor.org/docs/user-manual/#attributes[文档属性]。这些是 Asciidoctor 最强大的特性之一。文档属性是可以传递给 Asciidoctor 的参数，用以影响最终输出的生成方式。

在运行Asciidoclet时，使用一个或多个`-a`（或`--attribute`）选项来指定属性。`--attributes-file`选项从AsciiDoc文件中读取属性。这些属性在渲染Javadoc注释时传递给Asciidoctor。

这里有一些关于文档属性在你的Javadoc中可能如何有用的例子。

变量替换

在Javadoc注释或概述文件中的属性引用被替换为属性值。

/**
 * {product-name} 将改变你的生活！
 * @version {version}
 */

当使用 -a product-name=Foo -a version=1.0 参数运行doclet时，Asciidoctor会在生成的HTML输出中将所有[x-]{product-name}`和[x-]{version}`属性引用替换为给定的值。这使得在不改变源代码的情况下将值注入到Javadoc中变得非常简单。

条件包含

AsciiDoc的http://asciidoc.org/userguide.html#_conditional_inclusion_macros[条件指令]可以根据属性的存在与否选择性地包含内容。当相同的AsciiDoc源码在不同环境中使用时，这非常有用。

例如，如果你想在Javadoc概述页面和你的网站中重用相同的AsciiDoc内容，但有一些差异，你可以使用属性来告诉Asciidoctor在何时应该包含某些内容：

= Foo项目的文档

ifdef::javadoc[] // content that should only appear in Javadoc \endif::javadoc[]

ifdef::my-website[] // content that should only appear on the web site \endif::my-website[]

Asciidoclet在运行时自动设置`javadoc`属性，因此可以轻松选择仅限Javadoc的内容。当然，你也可以定义自己的属性。

Java和Ruby扩展支持

Asciidoctor可以使用Java或Ruby库进行扩展，Asciidoclet也继承了这种能力。

  • Java扩展在类路径中可用时会自动加载，使用http://asciidoctor.org/docs/asciidoctorj/#extension-spi[AsciidoctorJ的扩展SPI]。

  • Ruby库（Gems）通过使用`-r`（或`--require`）选项来加载。

Important
 在使用`--require`选项时，我们建议同时指定`--gem-path`选项，以明确设置已安装宝石的位置。这样做可以确保您的构建保持可移植性和可复制性。您可以使用https://github.com/torquebox/jruby-maven-plugins/blob/master/gem-maven-plugin/src/it/initialize/pom.xml[gem-maven-plugin]直接将宝石安装到您的构建目录中。

许多扩展都可用，但对于Javadoc作者可能最有用的一个是http://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram]。让我们看看它如何与Asciidoclet一起使用。

在Javadoc中嵌入图表

Asciidoctor Diagram是一个受欢迎的Asciidoctor扩展，它允许你在AsciiDoc源代码中嵌入纯文本图表描述，在Asciidoctor运行时会被渲染成图像。这在Javadoc中描述软件实现的架构或行为时可能极其有价值。

这是一个包含http://plantuml.sourceforge.net/index.html[PlantUML]序列图的Javadoc注释示例：

/**
 * This class implements the following protocol:
 *
 * [plantuml]
 * ....
 * Alice -> Bob: Authentication Request
 * Bob --> Alice: Authentication Response
 *
 * Alice -> Bob: Another authentication Request
 * Alice <-- Bob: another authentication Response
 * ....
 */
public class AuthServer { ... }

上图在Javadoc输出中的显示方式如下：

使用Asciidoctor Diagram的示例输出
Figure 2. 使用Asciidoctor Diagram的示例输出

并不错！开发者可以很容易地以纯文本的形式查看和更新图表，而且阅读Javadoc的用户将会看到美观的渲染图像。

许多其他类型的图表也得到支持，包括http://graphviz.org/[Graphviz]、http://blockdiag.com/[blockdiag]和http://ditaa.sourceforge.net/[ditaa]。更多示例，请参见http://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram文档]。

要在Asciidoclet中启用http://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram]支持：

  1. 安装Asciidoctor Diagram gem，asciidoctor-diagram：

    $ gem install asciidoctor-diagram

  2. 使用以下doclet选项运行Asciidoclet：

    --require asciidoctor-diagram
--gem-path ${env.GEM_PATH} (1)
--attribute data-uri (2)

    1. 选项 [x-]--gem-path ${env.GEM_PATH}` 告诉 Asciidoctor 的 JRuby 运行时在使用 --require 时在哪里找到 gems（有效地在内部设置了 $GEM_PATH 环境变量）。

    2. "`data-uri`属性是必要的，这样图像数据就会嵌入到生成的HTML文件中。脚注：[如果没有`data-uri`属性，Asciidoctor Diagram会将图像文件写到与生成的HTML不对应的位置。在撰写本文时，Asciidoctor Diagram正在解决这个问题。详情请参见https://github.com/asciidoctor/asciidoctor-diagram/issues/39[issue #39]。]"

  3. 欣赏你的Javadoc中装饰的美丽图表！

谢谢！

我们希望这个新版本能让你的Javadocs变得更好。我们感谢https://github.com/asciidoctor/asciidoclet/graphs/contributors[每一个对Asciidoclet做出贡献的人]。如果你有关于如何改进它的想法，我们总是欢迎通过https://github.com/asciidoctor/asciidoclet/[GitHub上的仓库]提出想法和拉取请求。