Vlákno názorů k článku
Java zavádza markdown syntax do komentárov od Saljack - Tohle je super, ale zrovna javadoc mě moc...

Tohle je super, ale zrovna javadoc mě moc netrápí a mám strach, že ta dokumentace bude pak roztříštěná jako např. v Python. Mnohem větší přínos pro mě měl JEP 413: Code Snippets in Java API Documentation

Prosím, co přesně na tom vidíte jako "super"?

Markdown je otřesný bastl, proto zde taky používají CommonMark, který se to snaží nějak usměrnit. Ano, někde je asi taková možnost soudobější (což neznamená nutně lepší) než psát Javadoc/HTML, ale zrovna tohle rozhodnutí mi přijde jako zcela zbytečné zesložitění implementace, která už tak není nikterak jednoduchá. Navíc to vyžaduje knihovnu commonmark-java, tedy další závislost...

Ani vlastně nevím, proč by to vůbec měl jazyk explicitně podporovat, když se jedná o komentáře, které by v příčetném prostředí měly být vyjmuty z interpretace. Maximálně by se na tento stupeň analýzy kódu mělo být možné připojit a udělat si tam nějaké další zpracování - přesně aby se nemusely dělat takové nesmysly.
Samozřejmě jazyk taky mohl mít od začátku systém na podporu metadat. Do toho se daly schovat jak typy, tak další informace, které by se daly automatizovaně zpracovat během překladu, při testování, nebo případně za běhu.

Markdown je ale lidsky čitelný - já si občas píšu v MD poznámky a čtu je v plaintextu.

HTML, XML nebo json jsou taky lidsky čitelné

A jsou lidí, pro které je čitelný i strojový kód

Sorry ale psát listy a tabulky v javadoc s html je prostě opruz a čitelnost v raw formátu to je dost na nic, což mě u formátu dokumentace přijde jako problém, protože to pak musím číst během code review. Navíc MD používám skoro všude, Wiki, Stackoverflow, Github, Gitlab atp. takže to je pro mě naprosto přirozená forma psaní. Tohle o html prostě říct nemůžu protože je to hrozný opruz psát ručně elementy. Jak už jsem psal největší pain s javadoc vyřešili se @snippet, do teď mi není jasné jak někdo může udělat dokumentační formát v kterém se špatně píše kód jazyka pro který je určen (ano anotace byly přidány dodatečně ale i tak).

Že to zesložiťuje implementaci, která je už tak složitá a zrovna MD se stejně skoro všude používá. A věřím, že zrovna architekti Java dobře vědí, co je ok a co není. A tady jasně převažuje čitelnost takové dokumentace nad nevýhodami zpracování.

Jenom pro srovnání:

/// Something `something`
///
/// This is *important*
/// # List
/// * item1
/// * item2
///
/// # Table
/// | Latin | Greek |
/// |-------|-------|
/// | a     | alpha |
/// | b     | beta  |
/// | c     | gamma |
///

vs

/**
 * Something `something`
 * <p>
 * This is <b>important</b>
 *
 * <h1> List</h1>
 * <ul>
 *   <li>item1</li>
 *   <li>item2</li>
 * </ul>
 *
 * <h1>Table</h1>
 * <table>
 *     <tr>
 *       <th>Lating</th>
 *       <th>Greek</th>
 *     </tr>
 *     <tr>
 *       <td>a</td>
 *       <td>alpha</td>
 *     </tr>
 *     <tr>
 *       <td>b</td>
 *       <td>beta</td>
 *     </tr>
 *     <tr>
 *       <td>c</td>
 *       <td>gamma</td>
 *     </tr>
 * </table>
 */

Mimochodem co ja bych dal za to i kdyby tady na root šlo psát MD.

6. 5. 2024, 08:57 editováno autorem komentáře

Prostě tooling je na nic, tak narveme všechno a kitchen sink přímo do jazyka/ platformy. To neumí jednoduchý nadpis, seznam a tabulku vyrenderovat IDE způsobem WYSIWYG přímo v komentáři? Mohl bych tam mít i pěkně udělané proporční písmo. Diff mimochodem může být také vyrenderovaný, když v komentáři rozpozná blok, který by bylo vhodné interpretovat/ renderovat.

Proč by to mělo renderovat IDE a všechno co to zobrazuje (code review, git, diff), když je tu řešení, které poskytuje pěknou čitelnost? Se změnou formátu se nic nemění stále to budete moci vidět naformátované v IDE. Navíc to vůbec neřeší, že zápis HTML v Javadoc je dost opruz a spoustu lidí to odradí aby dělali ty komentáře pěkné a formátované.
Další jazyky jako Rust, Kotlin, Go atd. mají dokumentační komentáře také postavené na MD, tak proč zrovna v Javadoc by to nemohl umět taky? Takže by se dalo říct, že MD syntax se stává standardem ve formátování dokumentačních komentářů.