きっかけ
Java23のリリースが近づいてきたので、事前調査。
Javaのリリース時期が、俺の誕生日と近いから、否が応でも思い出すんだよなぁ。。。
前提
- 環境準備は、sdkman使う。利用方法は明記しない。
- 2024/09/01時点での内容。
環境準備
sdkmanを使っているので、それで準備
$ sdk install java 23.ea.29-open
インストールされているか確認する。
現場猫ばりの確認をしないと、後続の作業がムダになる可能性もあるから、慎重に。
$ javac -version javac 23-ea $ java --version openjdk 23-ea 2024-09-17 OpenJDK Runtime Environment (build 23-ea+29-2309) OpenJDK 64-Bit Server VM (build 23-ea+29-2309, mixed mode, sharing)
これで環境準備完了
調査
内容
Google翻訳で翻訳かけてみたら以下になった。
JavaDoc ドキュメントのコメントを、HTML と JavaDoc タグの混合ではなく、Markdown で記述できるようにします
そのまんまだな。。。
とりあえず、書けるようになったらしいから試してみる。
サンプル実装
/// test markdown
///
/// _JEP 467_
///
/// - test1
/// - test2
/// - test3
///
/// [HashMapへのリンク](java.util.HashMap)
///
/// `1+1=2`
///
public class Jep467 {
/// サンプルコメント
///
/// | Latin | Greek |
/// |-------|-------|
/// | a | alpha |
/// | b | beta |
/// | c | gamma |
///
/// @param arg サンプル引数
/// @return "test"という文字列
public String test(String arg) {
return "test";
}
}
サンプルまねて書いただけ。
Javadocと違って、/// で書き始めるみたい。おそらく*だと、markdownの記法とごっちゃになるから変えたのだと思う。このコメントの書き方を見てると、VBAとかPythonのコメントっぽく見えるんだけど、俺だけ？※実際のコメント記述とは違うのだけれども。。。
Javadocに出力する。
ソースの階層に出力するとファイルがごちゃごちゃするので、フォルダ掘ってそこにだす。
$ mkdir javadoc $ cd javadoc/ $ javadoc ../Jep467.java
警告でちゃったけど、気にせずindex.htmlの内容をブラウザで見る。
Jep467を見てみる。
確かに、マークダウンで書いた内容がjavadocに書かれてある。
JEPの後ろの方にも書いてあるが、まだ全部のJavadocタグに対応した書き方があるわけではないらしい。
現に、@paramなんかは、まだMarkdownでの記載方法が決まっておらず、現行のJavadocの記述をするしかない。
感想
まずは一歩前進って印象。
個人的には、全部置き換え可能になったら使うかも。
現時点では、まだ使うには早いかなと思ってる。
markdown愛好家なので、早めに推し進めて欲しい。
Markdownは、はてブでもQiitaでも使ってたりするし、Obsidianでメモ書きによく使うから、早めに覚えておいて正解だったなと感じてる。
markdownって標準化されてないだろうと思ったのだが、commonMarkというのがあることを初めて知った。
調べてみると、いろいろ流派が出てくるが、commonMarkが主流っぽい？
※ここらへんは、歴史とか知らんので、下手に口出しできんな。。。
Javadocは、commonMark+GFMっぽい記述にするみたい。※Syntaxのところを抜粋
Markdown documentation comments are written in the CommonMark variant of Markdown. Enhancements to links allow convenient linking to other program elements. Simple GFM pipe tables are supported, as are all JavaDoc tags.
気になったんだが、JSDocどうするんだろう？
あれって、たしかJavadocみたいな記述をすると思うのだが、Markdownにも対応するのかな？
調べてみると、プラグインであるっぽいが、本体に入るのか分からないな。
Javaを主戦場にしてるけど、Javascript/Typescriptも使うので、ちょっと気になった。
関連リンク
CommonMark と GitHub Flavored Markdown (GFM) の違いと使い方 | sakakinox.net
