ドキュメンテーション
とあるプロジェクトでドキュメント作らないと割と大変な事になりそうと思って Delphi 用の JavaDoc クローン DelphiDoc を使おうと思ったんです。
が、2008 年の更新を最後に更新されてないわけです。
とはいえ、機能が完成しているから更新していないという可能性も高いし、使おうかなって思ったんですが、このまんま Markdown になったらいいなあという思考がよぎってしまい、勢いで作ってしまいました。
それが Markdown 形式で書かれたコメントをドキュメントとして出力する DelphiMDDoc です。
Markdown でコメントを！
まず、ドキュメンテーションの形式を考えないとなということで、次のようなルールを考えました。
(**
ここに Markdown を書く
*)
(* *)というのは Pascal の複文コメントの１つで、あんまり使われてない方なので、コレを使いました。
あとは、この (** *) で囲まれた領域を抽出して .md ファイルに纏めるだけで後は Markdown パーサが自動的に上手いことやってくれる訳です。
例えば、こんな風に書けます。
(**
### Method(Public)::publicm
* Bar
なんかやる関数
-- iParam
パラメータだよ
*)
procedure TFoo.Bar(const iParam: String);
begin
// 何か処理
end;
ここで不思議な記号が２つ出てきました。
::publicm
-- iParam
と書いてある所ですね。
Id 記号
まずは上の :: です。
これは、独自に拡張した「Id」と呼ぶ物です。
どういう機能かというと、同じ Id を持つ物を同じ場所に纏めます。
例えば
(**
# Foo::sample
Foo 関数。sample という Id を宣言
*)
procedure Foo;
begin
end;
(**
# Bar
Bar 関数。仲間はずれになる
*)
procedure Bar;
begin
end;
(**
::sample
# Baz
Baz 関数。sample という Id を宣言 Foo の近くに行く
*)
procedure Baz;
begin
end;
を変換すると…
# Foo
Foo 関数。sample という Id を宣言
# Baz
Baz 関数。sample という Id を宣言 Foo の近くに行く
# Bar
Bar 関数。仲間はずれになる
---
2019/03/11 00:24:15 Generated by DelphiMDDoc.
という Markdown が出力されます。
元のソースでは Foo, Bar, Baz と並んでいた関数が、Markdown では Foo, Baz, Bar となっていて Foo と Baz が一箇所にまとめられています。
これで、メソッドをどこに書いてもグルーピングされて表示されます。
レンダリングするとこうなります。
パラメータ記号
次に -- です。
これは単純にパラメータを書くときに箇条書き記号をインデントしてくれる物です。
先ほどの例でいえば、こんな Markdown が出力されます。
### Method(Public)
* Bar
なんかやる関数
* iParam
パラメータだよ
---
2019/03/11 00:41:43 Generated by DelphiMDDoc.
で、これをレンダリングすると…
こんな風に字下げされて表示されます。
Markdown で出来ることは何でも出来る
最終的に Markdown になるので、Markdown で出来ることは何でも出来ます。
(**
*)
とドキュメントに画像を入れたり
(**
[リンク](https://www.embarcadero.com/jp/products/delphi)
*)
なんてリンクを入れるのもお手の物です。
なんでもできます。
実際に変換する
リポジトリからソース一式をダウンロードしてコンパイルします。
すると DelphiMDDoc.exe ができあがるのでこれの引数にファイルやフォルダを渡します。
DelphiMDDoc D:\Sample\foo.pas
ファイルを渡すとそのファイルが markdown に変換されます。
上記の例だと foo.md が出漁されます。
DelphiMDDoc D:\Sample
フォルダを指定するとフォルダ内の拡張子が .pas, .dpr, .inc のファイルをみつけて markdown に変換します。
上記の例で D:\Sample フォルダ内に foo.pas, bar.dpr があった場合、foo.md, bar.md が出力されます。
実例
このプロダクトのコメントも MDDoc 形式で書いています。
なので、自分自身のソースを自分自身にかけると、下記の様になります。
一番左がソースコード、中央が出力された Markdown 、右が Markdown をレンダリングしたものです。
(クリックで拡大)
割と見た目がいいドキュメントになってると思いませんか…？
とはいえ
いやでもね、冷静に考えて。
JavaDoc → HTML と比べて DelphiMDDoc → Markdown → HTML と余計な階層を増やしてるんですよ…
しかも！画像貼れたりとかは JavaDoc でも出来るじゃん…？
まとめ
とはいえ、Markdown でコメント書けると、割となんか良い感じしませんかね？しませんか。そうですか。
メチャクチャ簡単な機構なんで、他の言語でも簡単に作れそう（２時間でできた）。