Skip to content

Instantly share code, notes, and snippets.

@Cristianoaf81GIT
Forked from gkhays/Javadoc-Markdown.md
Created July 14, 2021 13:36
Show Gist options
  • Select an option

  • Save Cristianoaf81GIT/55043957a8953a3bf52a62e1a92add1f to your computer and use it in GitHub Desktop.

Select an option

Save Cristianoaf81GIT/55043957a8953a3bf52a62e1a92add1f 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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment