<commit_before>= Asciidoclet
<NAME> <https://github.com/johncarl81>
v0.1.0
:source-highlighter: highlightjs

Asciidoclet is a Javadoc Doclet that allows you to write Javadoc using the AsciiDoc format.

== Introduction

Traditionally, Javadocs have mixed minor markup with HTML which, if you're writing for HTML Javadoc output, becomes
unreadable and hard to write over time. This is where lightweight markup languages like AsciiDoc thrive. AsciiDoc
straddles the line between readable markup and beautifully rendered content.

Asciidoclet incorporates an AsciiDoc renderer
(https://github.com/asciidoctor/asciidoctor[Asciidoctor] via the
https://github.com/asciidoctor/asciidoctor-java-integration[Asciidoctor Java integration] library)
into a simple Doclet that enables AsciiDoc formatting within Javadoc comments and tags.

== Example

Here's an example of a class with traditional Javadoc:

[source,java]
----
/**
 * <h1>Asciidoclet</h1>
 *
 * <p>Sample comments that include {@code source code}.</p>
 *
 * <pre>{@code
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     {@literal @}SuppressWarnings("UnusedDeclaration")
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * }</pre>
 *
 * @author <a href="https://github.com/johncarl81"><NAME></a>
 */
public class Asciidoclet extends Doclet {
}
----

and here's the same class with Asciidoclet:

[source,java]
----
/**
 * = Asciidoclet
 *
 * Sample comments that include +source code+.
 *
 * [source,java]
 * --
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     @SuppressWarnings("UnusedDeclaration")
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * --
 *
 * @author https://github.com/johncarl81[<NAME>]
 */
public class Asciidoclet extends Doclet {
}
----

The result is readable source and beautifully rendered Javadocs, the best of both worlds!

== Usage

Asciidoclet may be used via a maven-javadoc-plugin doclet:

[source,xml]
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <configuration>
        <source>1.7</source>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
            <groupId>org.asciidoclet</groupId>
            <artifactId>asciidoclet</artifactId>
            <version>${asciidoclet.version}</version>
        </docletArtifact>
    </configuration>
</plugin>

== License

....
Copyright 2013 <NAME>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and<commit_msg>synced with Asciidoctor docs<commit_after>= Asciidoclet
<NAME> <https://github.com/johncarl81>
v0.1.3
:description: This is a guide for setting up and using the Asciidoclet project. Asciidoclet is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.
:keywords: Asciidoclet, AsciiDoc, Asciidoctor, syntax, Javadoc, Doclet, reference
:awestruct-layout: base
:language: java
ifndef::awestruct[]
:idprefix:
:idseparator: -
:toc:
:sectanchors:
:icons: font
:source-highlighter: highlight.js
endif::awestruct[]
// Refs
:asciidoclet-src-ref: https://github.com/asciidoctor/asciidoclet
:asciidoc-ref: http://asciidoc.org
:asciidoctor-java-ref: http://asciidoctor.org/docs/install-and-use-asciidoctor-java-integration/
:asciidoclet-issues-ref: https://github.com/asciidoctor/asciidoclet/issues
:asciidoctor-src-ref: https://github.com/asciidoctor/asciidoctor
:asciidoctor-java-src-ref: https://github.com/asciidoctor/asciidoctor-java-integration
:discuss-ref: http://discuss.asciidoctor.org/

{asciidoclet-src-ref}[Asciidoclet] is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.

== Introduction

Traditionally, Javadocs have mixed minor markup with HTML which, if you're writing for HTML Javadoc output, becomes unreadable and hard to write over time. 
This is where lightweight markup languages like {asciidoc-ref}[AsciiDoc] thrive. 
AsciiDoc straddles the line between readable markup and beautifully rendered content.

Asciidoclet incorporates an AsciiDoc renderer (Asciidoctor via the {asciidoctor-java-ref}[Asciidoctor Java integration] library) into a simple Doclet that enables AsciiDoc formatting within Javadoc comments and tags.

== Example

Here's an example of a class with traditional Javadoc.

[source]
.A Java class with traditional Javadoc
----
/**
 * <h1>Asciidoclet</h1>
 *
 * <p>Sample comments that include {@code source code}.</p>
 *
 * <pre>{@code
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     {@literal @}SuppressWarnings("UnusedDeclaration")
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * }</pre>
 *
 * @author <a href="https://github.com/johncarl81"><NAME></a>
 */
public class Asciidoclet extends Doclet {
}
----

This is the same class with Asciidoclet.

[source]
.A Java class with Asciidoclet Javadoc
----
/**
 * = Asciidoclet
 *
 * Sample comments that include +source code+.
 *
 * [source,java]
 * --
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     @SuppressWarnings("UnusedDeclaration")
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * --
 *
 * @author https://github.com/johncarl81[<NAME>]
 */
public class Asciidoclet extends Doclet {
}
----

The result is readable source and beautifully rendered Javadocs, the best of both worlds!

== Usage

=== Maven

Asciidoclet may be used via a +maven-javadoc-plugin+ doclet:

[source,xml]
----
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <configuration>
        <source>1.7</source>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
            <groupId>org.asciidoclet</groupId>
            <artifactId>asciidoclet</artifactId>
            <version>${asciidoclet.version}</version>
        </docletArtifact>
    </configuration>
</plugin>
----

=== Gradle

Asciidoclet may be used via a doclet in the +Javadoc+ task:

[source,groovy]
----
configurations {
    asciidoclet
}

dependencies {
    asciidoclet 'org.asciidoctor:asciidoclet:0.+'
}
 
javadoc {
    options.docletpath = configurations.asciidoclet.files.asType(List)
    options.doclet = 'org.asciidoctor.Asciidoclet'
}
----

== Rescources and help

For more information:

* {asciidoclet-src-ref}[Asciidoclet Source Code]
* {asciidoclet-issues-ref}[Asciidoclet Issue Tracker]
* {asciidoctor-src-ref}[Asciidoctor Source Code]
* {asciidoctor-java-src-ref}[Asciidoctor Java Integration Source Code]

If you have questions or would like to help develop this project, please join the {discuss-ref}[Asciidoctor discussion list].

== License

....
Copyright 2013 <NAME>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
{'fraction_non_alphanumeric': 0.11049188272352799, 'fraction_numerical': 0.005694208868427429, 'mean_word_length': 3.9788902291917974, 'pattern_counts': {'":': 0, '<': 73, '<?xml version=': 0, '>': 73, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5346120', 'n_tokens_mistral': 2706, 'n_tokens_neox': 2604, 'n_words': 745}