Markdown w komentarzach Javadoc
Pisz komentarze Javadoc w Markdown zamiast HTML dla lepszej czytelności.
Porównanie kodu
✕ Java 8
/**
* Returns the {@code User} with
* the given ID.
*
* <p>Example:
* <pre>{@code
* var user = findUser(123);
* }</pre>
*
* @param id the user ID
* @return the user
*/
public User findUser(int id) { ... }
✓ Java 23+
/// Returns the `User` with
/// the given ID.
///
/// Example:
/// ```java
/// var user = findUser(123);
/// ```
///
/// @param id the user ID
/// @return the user
public User findUser(int id) { ... }
Widzisz problem z tym kodem? Daj nam znać.
Dlaczego nowoczesne podejście wygrywa
Naturalna składnia
Używaj grawisów dla kodu inline i ``` dla bloków zamiast tagów HTML.
Łatwiejsze pisanie
Żadnego {@code}, <pre>, tagów <p> — pisz po prostu w Markdown.
Lepiej w edytorach
Markdown renderuje się pięknie w nowoczesnych IDE i edytorach tekstu.
Stare podejście
Javadoc oparty na HTML
Nowoczesne podejście
Javadoc w Markdown
Od JDK
23
Poziom trudności
Początkujący
Wsparcie JDK
Markdown w komentarzach Javadoc
Dostępne
Dostępne od JDK 23 (wrzesień 2024)
Jak to działa
Java 23 wprowadza komentarze Javadoc w stylu /// Markdown jako alternatywę dla tradycyjnego formatu /** */ opartego na HTML. Składnia Markdown jest bardziej naturalna do pisania i czytania, z obsługą bloków kodu, wyróżnienia, list i linków. Kompilator konwertuje Markdown do HTML dla wyjścia javadoc.
Powiązana dokumentacja
Dowód