Using Markdown in Javadoc

Javadoc-Markdown.md

Background: A Google search led me to the source code (on GitHub) for ng_model.ts#L124 wherein it looked like the documentation was Javadoc, but with Markdown syntax.

...
* ### Setting the ngModel name attribute through options
*
* The following example shows you an alternate way to set the name attribute. The name attribute is used
* within a custom form component, and the name `@Input` property serves a different purpose.
*
* ```html
* <form>
*   <my-person-control name="Nancy" ngModel [ngModelOptions]="{name: 'user'}">
*   </my-person-control>
* </form>
* <!-- form value: {user: ''} -->
* ```
*
* @ngModule FormsModule
* @publicApi
*/

ng_model.ts - jump to definition

Note: GitHub now has a jump to definition feature.

Sure enough, Markdown in Javadoc is a thing! From the blog of Michael Scharhag:

Using Markdown syntax in Javadoc comments

Set up the Maven Javadoc plugin

<build>
  <plugins>
    <plugin>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.9</version>
      <configuration>
        <doclet>ch.raffael.doclets.pegdown.PegdownDoclet</doclet>
        <docletArtifact>
          <groupId>ch.raffael.pegdown-doclet</groupId>
          <artifactId>pegdown-doclet</artifactId>
          <version>1.1</version>
        </docletArtifact>
        <useStandardDocletOptions>true</useStandardDocletOptions>
      </configuration>
    </plugin>
  </plugins>
</build>

Example using Markdown in Javadoc

/**
* ## Large headline
* ### Smaller headline
*
* This is a comment that contains `code` parts.
*
* Code blocks:
*
* ```java
* int foo = 42;
* System.out.println(foo);
* ```
*
* Quote blocks:
*
* > This is a block quote
*
* lists:
*
*  - first item
*  - second item
*  - third item
*
* This is a text that contains an [external link][link].
*
* [link]: http://external-link.com/
*
* @param id the user id
* @return the user object with the passed `id` or `null` if no user with this `id` is found
*/
public User findUser(long id) {
  ...
}

Generate

mvn javadoc:javadoc

References

1. Using Markdown syntax in Javadoc comments (Michael Scharhag)
2. Using Markdown Syntax in Javadoc (DZone)
3. Stackoverflow markup for javadoc (StackOverflow)
4. Are there some good and modern alternatives to Javadoc? [closed] (StackOverflow)
5. A Doclet that allows the use of Markdown in JavaDoc comments (GitHub)
6. Markdown Doclet for Javadoc (Richard Nichols)
7. Javadoc (Wikipedia)
8. javadoc - Generates HTML pages of API documentation from Java source files (Oracle)