search

Abnaxos / markdown-doclet

A Doclet that allows the use of Markdown in JavaDoc comments.
GNU General Public License v3.0
319 stars 40 forks source link

readme

Markdown Doclet

A Doclet that allows the use of Markdown and PlantUML in JavaDoc comments. It uses Pegdown as Markdown processor. It's a simple preprocessor to the standard Doclet: It processes all JavaDoc comments in the documentation tree and then forwards the result to the standard Doclet. The JavaDoc output by this Doclet for this Doclet can be found here.

This Doclet is released under the GPL 3.0.

Leading Spaces

Sometimes, leading whitespaces are significant in Markdown. Because of the way we usually write JavaDoc comments and the way JavaDoc is implemented, this may lead to some problems:

/**
 * Title
 * =====
 *
 * Text
 */

In this example, each line has one leading space. Because of this, the title won't be recognised as such by Pegdown. To work around this problem, the Doclet uses a simple trick: The first leading space character (the actual space character, i.e. \\u0020) will be cut off, if it exists.

This may be important e.g. for code blocks, which should be indented by 4 spaces: Well, it's 5 spaces now. ;)

Note: If an overview.md file is specified, leading spaces will be treated normally in this file. The first space will not be ignored.

This behaviour is currently not customisable.

Javadoc Tags

The following known tags handled by Pegdown so you can use Markup with them:

@see Tags

The @see tag is a special case, as there are several variants of this tag. These two variants will remain unchanged:

The third variant however, which is originally meant to refer to a printed book, may also contain Markdown-style links:

These are all rendered as @see <a href="http://www.example.com/">LABEL</a>, where LABEL falls back to the link's URL, if no label is given.

Custom Tag Handling

Tag handling can be customised by implementing your own TagRenderers and registering them with the PegdownDoclet. You'll have to write your own Doclet, though, there's currently no way to do this using the command line. See the JavaDocs and sources for details on this.

This currently only works for block tags.

Handling of '@'

'@' at the beginning of a new line introduces the tag block. This is very inconvenient especially in example code blocks:

 /**
  * Java Example:
  *
  * ```java
  * @Override
  * public void myMethod() {
  * }
  * ```
  */

The tag block will start with @Override and the rest of the documentation block will be cut off. There's unfortunately no way to circumvent this. However, the Doclet provides a discrete way to escape such leading '@' signs:

 /**
  * Java Example:
  *
  * ```java
  * .@Override
  * public void myMethod() {
  * }
  * ```
  */

Note the leading dot in .@Override. This dot will not be rendered in the JavaDoc. If you really meant .@, add another dot: ..@ will be rendered as .@. This only works for the '@' sign and only at the beginning of a line.

Custom Markdown Taglet

How to define your own Markdown Taglet

Gist Markdown Taglet ({{gist gistid}})

see Description Of Gist Taglet

PlantUML

This Doclet has built-in support for PlantUML. Just use the @uml tag:

/**
 * Description.
 *
 * ![Example Diagram](example.png)
 *
 * @uml example.png
 * Alice -> Bob: Authentication Request
 * Bob --> Alice: Authentication Response
 */

It's also possible to use @startuml and @enduml instead, as usual. @startuml is simply a synonym for @uml and @enduml will be ignored entirely. Use this for compatibility with other tools, like e.g. the PlantUML IDEA Plugin.

Syntax Highlighting

The Pegdown Doclet integrates highlight.js to enable syntax highlighting in code examples. See "Fenced code blocks" below for details.

Invoking

Download markdown-doclet-<version>-all.jar from the Maven repository and specify it on the command line:

javadoc -doclet ch.raffael.mddoclet.MarkdownDoclet -docletpath /path/to/markdown-doclet-<version>-all.jar

It supports all options the standard Doclet supports and some additional options:

Locale

There's an annoying issue with Javadoc: If the locale is not set to exactly en, it won't work with HTML tags correctly when determining the first sentence. For instance, of you start your comment with a title (which using Markdown actually encourages to do, at least in package descriptions), the closing </h1> tag will not be recognised:

/**
 * * My Title
 *
 * Text goes here. More details follow.
 */

With a locale other than 'en', only the dot ('.') is recognised as sentence end resulting in the following summary:

My Title Text goes here.

If the locale is en and no break iterator is set, the </h1> after "My Title" is recognised as sentence end.

I'd therefore recommend to set the locale explicitly to en.

See also: Issue #44

Gradle

Add the following to your build.gradle to use the doclet with Gradle:

buildscript {
    repositories {
        mavenCentral() // or jcenter()
    }
    dependencies {
        classpath 'ch.raffael.markdown-doclet:markdown-doclet:1.4'
    }
}

apply plugin: 'ch.raffael.markdown-doclet'

Maven

Add the following to your POM to use the doclet with Maven:

<build>
  <plugins>
    <plugin>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.9</version>
      <configuration>
        <doclet>ch.raffael.mddoclet.MarkdownDoclet</doclet>
        <docletArtifact>
          <groupId>ch.raffael.markdown-doclet</groupId>
          <artifactId>markdown-doclet</artifactId>
          <version>1.4</version>
        </docletArtifact>
        <useStandardDocletOptions>true</useStandardDocletOptions>
      </configuration>
    </plugin>
  </plugins>
</build>

The doclet is available in Maven Central.

IDE support

There is a plugin that enables Ctrl-Q in IntelliJ IDEA. Just download it from the plugin repository ("Settings -- Plugins -- Browse Repositories"), or build it yourself (see integrations/idea-plugin/README.md).

Use the PlantUML integration plugin for a live preview while editing PlantUML diagrams. This only works if you use the "classic" @startuml and @enduml tags.

If you think your favourite IDE is missing, feel free to add a plugin for it and send me a pull request. ;)

Markdown Extensions