このブログはLazarus(FreePascal)アドベントカレンダー16日目の記事です。
Lazarus(というかPascal)ではメソッドの使用方法などを紹介するために、ドキュメントコメントを設定することができます。
Pascalにおけるドキュメントコメントは、XMLの形式をとっています*1。
{・・・} /// <summary>関数の説明</summary> /// <param name="ScriptFile">引数1の説明</param> /// <param name="StdOut">引数2の説明</param> /// <param name="StdOut">引数3の説明</param> /// <returns>戻り値の説明</returns> function Execute(ScriptFile: String; out StdOut: String; out StdErr: String): Integer; {・・・}
ちゃんと書かれていると、関数をマウスでホバーしたときにヒントが表示されるようになります。
XMLで書いてる意味ないじゃん！という気がしなくもないです。まあDelphiだともうちょっと読みやすい形式が出てくるようですが。
で、このドキュメントコメントですが、Pascalの場合メソッドの宣言部に書きます。実装部に書いてもなにもないのでご注意ください。
FPDocエディタ
いちおう、Lazarusには入力を支援するツールして、FPDocエディタというものがあります。
ただ個人的には使い方がよくわからなかった・・・ いちおう公式Wikiにも使い方は書いてあるのですが、結局よくわからず・・・。あれ使えている人いるんでしょうかねえ。
ただ、実際にどれほどの効果があるかどうかはともかく、メソッドの使い方がある程度書いてあると第三者が読んだときにかなり解析が楽になります(Free Pascal標準ライブラリのソースを読んだときの感想)。
XML書式を使うかどうかはともかく、積極的にコメントを書いていくと良いでしょう。
