Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skills/optional/java/java-markdown-doc-comments/SKILL.md

Raw
Rendered preview

name: java-markdown-doc-comments description: "Use when writing or reviewing JDK 23+ Javadoc comments with /// Markdown syntax." license: CC-BY-4.0-summary compatibility: "JDK 23+" metadata: sources: - "https://openjdk.org/jeps/467"

Markdown Documentation Comments

Use for Markdown Documentation Comments work from JEP 467 when targeting JDK 23+.

When active

  • Use /// documentation comments with CommonMark.
  • Use Markdown links to program elements, e.g. [List] or [text][List].
  • Keep @param, @return, and other Javadoc tags when useful; tag bodies use Markdown.

Pitfalls

  • Plain blank lines terminate a /// doc comment.
  • Use HTML tables when captions/accessibility are needed.
  • Older Javadoc tools do not understand Markdown comments.

Examples

Read examples/jep-467.md for JEP-derived snippets.

References

---
name: java-markdown-doc-comments
description: "Use when writing or reviewing JDK 23+ Javadoc comments with `///` Markdown syntax."
license: CC-BY-4.0-summary
compatibility: "JDK 23+"
metadata:
  sources:
    - "https://openjdk.org/jeps/467"
---

# Markdown Documentation Comments

Use for **Markdown Documentation Comments** work from [JEP 467](https://openjdk.org/jeps/467) when targeting JDK 23+.

## When active

- Use `///` documentation comments with CommonMark.
- Use Markdown links to program elements, e.g. `[List]` or `[text][List]`.
- Keep `@param`, `@return`, and other Javadoc tags when useful; tag bodies use Markdown.

## Pitfalls

- Plain blank lines terminate a `///` doc comment.
- Use HTML tables when captions/accessibility are needed.
- Older Javadoc tools do not understand Markdown comments.

## Examples

Read `examples/jep-467.md` for JEP-derived snippets.

## References

- https://openjdk.org/jeps/467