我们很高兴地宣布 Asciidoctor 家族的最新成员 Asciidoclet 的加入。https://github.com/asciidoctor/asciidoclet[Asciidoclet] 是一个基于 Asciidoctor 的 Javadoc Doclet，它使得开发人员能够使用 AsciiDoc 语法编写 Javadoc 注释。

动机

从一开始，Java的设计者们就做对了一件事，那就是将文档与源代码一起包括在内。这使得文档能够更紧密地与不断变化的源代码保持同步，并允许在多个查看平台上查看，最值得注意的是HTML生成和IDE集成。

Javadoc的主要缺点一直是需要使用嵌入的HTML片段来实现高级（甚至是适度的）格式化。这正是http://asciidoc.org[AsciiDoc]集成发挥作用的地方。作为一种轻量级标记语言，http://asciidoc.org[AsciiDoc]让开发者可以不用涉足底层HTML标记就获得高级格式。换句话说，开发者可以专注于_内容_而不是_标记_，仍然能够得到一个精美的最终结果。

将AsciiDoc与Javadocs结合使用意味着源码可读性强并且Javadocs渲染得非常美观，兼具两者的优点！

用法

一旦https://github.com/asciidoctor/asciidoclet[Asciidoclet]集成到Javadoc中，就只需要在Javadocs中使用http://asciidoc.org[AsciiDoc]标记。以下示例展示了一系列https://github.com/asciidoctor/asciidoclet[Asciidoclet]的特性：

/**
 * = Asciidoclet (1)
 星号
 * 包含+源代码+的样本评论。(2)
 星号
 * [source,java] (3)
 * 破折号
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 星号
 *     @SuppressWarnings("UnusedDeclaration") (4)
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     右大括号
 * 右大括号
 * 破折号
 星号
 * 作者 https://github.com/johncarl81 [John Ericksen] (5)
*/ public class Asciidoclet extends Doclet { }

  1. 使用 = 标记可以轻松创建标题。

  2. 段落是默认的，并且不需要使用`<p>HTML标签。内联源码可以通过用+`符号包围文本来进行标记。

  3. 源代码可以通过使用 [source,language] 标签和块定界符 --，也称为“围栏”，来轻松标记。

  4. 臭名昭著的+@符号被https://github.com/asciidoctor/asciidoclet[Asciidoclet]自动处理，避免了标准的{@literal @}+样板文件。

  5. 内联http://asciidoc.org[AsciiDoc]标记可在Javadoc标签内使用。此例突出了链接的渲染。

分布

Asciidoclet发布至Maven Central。下表总结了构件信息。

Asciidoclet的工件信息
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

0.1.3*

pom jar javadoc (jar) source (jar)

这个版本是基于Asciidoctor 0.1.3版本的。

安装

'Asciidoclet 是一个标准的 Javadoc Doclet，可以作为这样的工具使用。安装 Asciidoclet 最简单的方法之一就是将它作为 Doclet 添加到 maven-javadoc-plugin 中：'

Maven Doclet声明
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
           <groupId>org.asciidoctor</groupId>
           <artifactId>asciidoclet</artifactId>
           <version>${asciidoclet.version}</version>
        </docletArtifact>
    </configuration>
</plugin>

我们希望这个扩展能帮助你将你的Javadoc推向新的高度。一如既往，我们欢迎合作，你可以在https://github.com/asciidoctor/asciidoclet[GitHub]上找到（并分叉）源代码。

非常感谢https://github.com/lordofthejars[Alex Soto]来自https://github.com/asciidoctor/asciidoctor-java-integration[Asciidoctor Java integration project]，以及https://github.com/lightguard[Jason Porter]和https://github.com/mojavelinux[Dan Allen]为他们的反馈和支持，还有每一个为Asciidoctor项目做出贡献的人。由于Asciidoctor社区的出色工作和协作，编写这个扩展变得异常简单。