Skip to content

Instantly share code, notes, and snippets.

@gkhays
Last active November 21, 2023 14:26
Show Gist options
  • Save gkhays/a80642ecd8fe476d7220b7940fec5ad0 to your computer and use it in GitHub Desktop.
Save gkhays/a80642ecd8fe476d7220b7940fec5ad0 to your computer and use it in GitHub Desktop.
Using Markdown in Javadoc

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.

jump2def

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)
@gkhays
Copy link
Author

gkhays commented Aug 23, 2019

jump2def

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment