Skip to content

Instantly share code, notes, and snippets.

@marcusadair

marcusadair/!javadoc.md

Last active June 20, 2025 18:24
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save marcusadair/ff636e821f17d99dbd27727c10f77ae7 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save marcusadair/ff636e821f17d99dbd27727c10f77ae7 to your computer and use it in GitHub Desktop.
Download ZIP
Javadoc quick ref
Raw
!javadoc.md

Javadoc Markdown Examples

Raw
Java24Javadoc.java
/// Java 24 Javadoc with Markdown
///
/// Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo
/// ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis.
///
/// # Headings
///
/// Prefix and underscore heading styles work (atx and setext):
/// - Underscore with `==...` for level 1.
/// - Underscore with `--...` for level 2.
///
/// # Horizontal rules
///
/// Horizontal rule is created using `***` standalone on a line.
///
/// ***
///
/// ## Inline formatting
///
/// _Emphasis_, __bold__, `code in backticks`.
/// - Triple for ***bold and italic***.
/// - ___Equally with underscores___.
/// - The tres<sup>comma</sup> club
/// - Base<sub>2</sub>
///
/// ## References
///
/// - [Oracle Javadoc Guide](https://docs.oracle.com/en/java/javase/24/javadoc/using-markdown-documentation-comments.html)
/// - [Javadoc Spec](https://docs.oracle.com/en/java/javase/24/docs/specs/javadoc/doc-comment-spec.html)
///
/// @see #blockquotes()
/// @see #codeblocks()
/// @see #images()
/// @see #links()
/// @see #lists()
/// @see #snippets()
/// @see #tables()
/// @version r1
public class Java24JavadocWithMarkdown {
/// # Lists
///
/// ## Bullet lists
///
/// - Using hyphen.
/// + Using plus.
/// * Using asterisk.
///
/// ## Numbered lists
///
/// 1. Check
/// 2. One
/// 3. Two
///
/// ## Task lists
///
/// - [ ] Task
/// - [x] List – broken in IDEA (June 2025)
///
void lists() {}
/// # Links
///
/// ## Code references
/// Short-form reference link examples from JEP 467:
///
/// - module [java.base/]
/// - package [java.util]
/// - class [String]
/// - field [String#CASE_INSENSITIVE_ORDER]
/// - method [String#chars()]
///
/// Alternative text support:
///
/// - [the `java.base` module][java.base/] - broken in IDEA (June 2025)
/// - [the `java.util` package][java.util] - broken in IDEA (June 2025)
/// - [a class][String]
/// - [a field][String#CASE_INSENSITIVE_ORDER]
/// - [a method][String#chars()]
///
/// ## Escaping
///
/// Square brackets in reference links must be escaped.
/// For instance with an array param:
///
/// - [String#copyValueOf(char\[\])]
///
/// ## URLs
///
/// Other Markdown link forms should work:
///
/// - [JEP 467](https://openjdk.org/jeps/467)
///
/// ## Deep links
///
/// > To create a link to user-defined and implicitly defined IDs in the
/// > generated documentation use the ## notation. For example, the Java SE
/// > class MemoryLayout has a heading Access mode restrictions with a
/// > corresponding anchor access-mode-restrictions. The following example
/// > shows a link to that anchor:
///
/// - [Access mode restrictions][java.lang.foreign.MemoryLayout##access-mode-restrictions]
/// - But this is broken in IDEA (June 2025)
///
/// ## Link references
///
/// But it seems we cannot use normal link reference definitions,
/// as shown in this fenced code block:
///
/// ```markdown
/// Doesn't work:
///
/// [JEP467]: https://openjdk.org/jeps/467 "Doesn't work(?)"
/// [JEP467]: <https://openjdk.org/jeps/467> "Unless it is only a Jetbrains issue?"
/// [JEP467]: https://openjdk.org/jeps/467
/// ```
///
/// ## References
/// - [Links in the Javadoc Spec](https://docs.oracle.com/en/java/javase/24/docs/specs/javadoc/doc-comment-spec.html#links)
/// – from the verbiage here it appears that reference link declarations should work!
void links() {}
/// # Code blocks
///
/// ## Fenced
///
/// Code block fences may be backticks or tildes:
///
/// ~~~
/// var x = 1 + 1;
/// var y = 2 * 2;
/// ~~~
///
/// ## Indented
///
/// Code blocks may be marked by indentation:
///
/// # Indented code block is broken IDEA (June 2025)
/// var x = 1 + 1;
/// var y = 2 * 2;
void codeblocks() {}
/// # Tables
///
/// Uses [GFM](https://github.github.com/gfm/#tables-extension-) syntax.
///
/// | Latin | Greek |
/// |------:|-------|
/// | a | alpha |
/// | b | beta |
/// | c | gamma |
///
void tables() {}
/// # Block quotes
///
/// > This is a blockquote.
/// >
/// > It can span multiple lines.
///
/// ## Nested
/// > Block quotes can nest:
/// >
/// > > Inner quote.
/// >
/// > Outer quote.
///
/// ## Containing markdown
/// > Block quotes can take markdown:
/// >
/// > #### Heading
/// >
/// > - Item
/// > - Item
/// >
/// > ```java
/// > System.out.println("Welcome");
/// > ```
///
/// ## References
///
/// - [Jetbrains blog](https://blog.jetbrains.com/idea/2025/04/markdown-in-java-docs-shut-up-and-take-my-comments/)
void blockquotes() {}
/// # Images
///
/// ![Java Logo](https://www.oracle.com/a/tech/img/cb88-java-logo-001.jpg)
void images() {}
/// # Snippets
///
/// These work as before:
///
/// {@snippet :
/// /* this comment is a problem in normal javadoc */
/// // @replace region substring='"Hello"' replacement='"yo"' :
/// System.out.println("Hello"); // @highlight
/// System.out.println("Hello"); // @highlight regex='".*"'
/// System.out.println("Hello"); // not highlighted
/// System.out.println("Hello"); // @link substring="println" target=PrintStream#println(String)
/// System.out.println("x"); // @replace substring='"x"' replacement='...'
/// // @replace substring='"x"' replacement='...' :
/// System.out.println("x");
/// // note colon ending the comment line above
/// }
///
/// ## Features
///
/// - Highlighting and text replacements.
/// - Sourcing from files.
/// - Regions for both inline and sourced snippets.
/// - `lang` attribute, but only for `java` and `properties`.
/// - `id` attribute, passing it through to HTML output.
///
/// ## Markup tags
///
/// - Applied in comments, called _markup comments_.
/// - Multiple markup tags can be in the same comment.
/// - Normally applies to the same source line.
/// - Applies to the next source line when terminated by `:`.
/// - Unrecognized markup tags are ignored.
///
/// ### `@highlight` args
///
/// - `substring` — literal to be highlighted
/// - `regex` — pattern to be highlighted
/// - `region` — scope
/// - `type` — `bold`, `italic`, `highlighted` (default)
///
/// ### `@replace` args
///
/// - `substring` — literal to be replaced
/// - `regex` — pattern to be replaced
/// - `region` — scope
/// - `replacement` — replacement text
///
/// ### `@link` args
///
/// `substring` — literal to be linked
/// `regex` — pattern to be linked
/// `region` — scope
/// `target` — link target
/// `type` — `link` (default) or `linkplain`
///
/// ### Regions
///
/// - `region=name` isn't always necessary.
/// - Plain `@end` will end the nearest.
///
/// ```
/// // @start region=r1
/// // @highlight region=r2
/// // @replace region=r3
/// // @link region=r4
/// ...
/// // @end region=r4
/// // @end region=r3
/// // @end region=r2
/// // @end region=r1
/// `````
///
/// # References
/// - [Snippets in the Javadoc guide](https://docs.oracle.com/en/java/javase/24/javadoc/snippets.html)
/// - [Snippets in the Javadoc spec](https://docs.oracle.com/en/java/javase/24/docs/specs/javadoc/doc-comment-spec.html#snippet)
/// - [JEP 413](https://openjdk.org/jeps/413) finalized for Java 18.
void snippets() {}
/// # Tags
///
/// | Tag | Notes |
/// | --------------------------------- | ----------------------- |
/// | `@author name-text` | |
/// | `{@code text}` | |
/// | `{@deprecated text}` | |
/// | `{@docRoot}` | |
/// | `@exception name desc` | |
/// | `@hidden` | |
/// | `{@index word desc}` | since 9 |
/// | `{@index "phrase" desc}` | |
/// | `{@inheritDoc}` | |
/// | `{@inheritDoc type}` | _type_ arg since 22 |
/// | `{@link ref label}` | |
/// | `{@linkplain ref label}` | |
/// | `{@literal text}` | |
/// | `@param name desc` | |
/// | `@param name {@inheritDoc}` | |
/// | `@param <t> desc` | |
/// | `@provides service desc` | since 9, see `@uses` |
/// | `@return desc` | |
/// | `@return {@inheritDoc}` | |
/// | `{@return desc}` | inline form since 16 |
/// | `{@return {@inheritDoc}}` | 〃 |
/// | `@see "string"` | no link |
/// | `@see <a href="url">label</a>` | |
/// | `@see ref label` | |
/// | `@serial field-desc` | |
/// | `@serial include` | |
/// | `@serial exclude` | |
/// | `@serialData desc` | |
/// | `@serialField name type desc` | |
/// | `@since text` | |
/// | `{@snippet attrs }` | since 18 |
/// | `{@snippet attrs : body }` | 〃 |
/// | `{@snippet attrs : body }` | 〃 |
/// | `@spec url title` | since 20 |
/// | `{@summary text}` | since 10 |
/// | `{@systemProperty name}` | since 12 |
/// | `@throws name desc` | |
/// | `@uses service desc` | since 9, see `@provides`|
/// | `{@value field-ref}` | |
/// | `{@value format field-ref}` | _format_ arg since 20 |
/// | `@version text` | |
///
/// - See [#snippets] for markup comment tags:
/// `@start`, `@end`, `@highlight`, `@replace`, `@link`.
///
/// ## Tag locations
///
/// | Tag |Module |Package| Type | Cnstr |Method | Field | Other |
/// |----------------|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|
/// | author | ✓ | ✓ | ✓ | | | | ✓ |
/// | code | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | deprecated | ✓ | | ✓ | ✓ | ✓ | ✓ | |
/// | docRoot | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | exception | | | | ✓ | ✓ | | |
/// | hidden | | | ✓ | | ✓ | ✓ | |
/// | index | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | inheritDoc | | | | | ✓ | | |
/// | link | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | linkplain | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | literal | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | param | | | ✓ | ✓ | ✓ | | |
/// | provides | ✓ | | | | | | |
/// | return | | | | | ✓ | | |
/// | see | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | serial | | ✓ | ✓ | | | ✓ | |
/// | serialData | | | | | * | | |
/// | serialField | | | | | | * | |
/// | since | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | snippet | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | summary | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | systemProperty | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | throws | | | | ✓ | ✓ | | |
/// | uses | ✓ | | | | | | |
/// | value | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
/// | version | ✓ | ✓ | ✓ | | | | ✓ |
///
/// Inline and block tags still work as normal.
/// Tags that support markup now also support markdown (see `@param` tags below).
///
/// ## References
///
/// - [Javadoc Spec](https://docs.oracle.com/en/java/javase/24/docs/specs/javadoc/doc-comment-spec.html#standard-tags)
///
/// @param a _left_ side
/// @param b _right_ side <- we have formatting
void tags(int a, int b) {}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment