はじめに
Delphi 10.4.2 Sydney で XML ドキュメントコメントを書いていて**「ん？」**と思ったので記事にしてみました。
XML ドキュメントコメント
Delphi 2007 以降では (というか Delphi 2007 以降で "も") トリプルスラッシュ (///) で始まるコメントは XML ドキュメントコメントとして扱われます。
例えば、このような関数があったとします。
function Test(a, b: Integer): Integer;
begin
result := a * b;
end;
Test() 関数の直上に次のような XML ドキュメントコメントを記述できます。
/// <summary>
/// テスト関数
/// </summary>
/// <param name="a">
/// 被乗数
/// </param>
/// <param name="b">
/// 乗数
/// </param>
/// <returns>
/// a * b の結果を返します。
/// </returns>
/// <remarks>
/// 特に意味のない関数です。
/// </remarks>
function Test(a, b: Integer): Integer;
begin
result := a * b;
end;
XML ドキュメントコメントはコードエディタで折りたたむことができます。
See also:
ヘルプインサイト
Test() 関数が使われている場所でヘルプインサイトを表示させると、ソースコード中に記述した Test() 関数の XML ドキュメントコメントがポップアップで表示されます。
ヘルプインサイトは
- コードエディタでマウスポインタを識別子の上に置いてしばらく待つ。
-
〔Ctrl〕+〔Shift〕+〔H〕を押す。
いずれかの方法で表示できます。
See also:
Delphi 10.4.2 におけるヘルプインサイト
Delphi 10.4 で LSP (Language Server Protocol) が実装され、10.4.2 において *.dpr (コンソールアプリケーションを含む Delphi プロジェクトファイル) でも LSP が正しく動作するようになった影響なのか、*.dpr でもヘルプインサイトで XML ドキュメントコメントが使えるようになっているようです。
以前のバージョンでは *.dpr 内ではヘルプインサイトが効かなかったと記憶しています。
試しに Delphi 10.4.2 で LSP を切ってみると、*.dpr でのヘルプインサイトで XML ドキュメントコメントが無視されました。
See also:
ドキュメントコメントがヘルプインサイトに表示されない？
記述方法によってはドキュメントコメントがヘルプインサイトに表示されない事があるようです。古い Delphi (IDE) のバグのような気がするのですが...。
・可視性セクション
高度なレコード型でメソッド定義の前に public 等の可視性指定子がないとドキュメントコメントが表示されなかったり、最上位にあるメソッドのドキュメントコメントがそれ以降のメソッドにも表示される事があるようです。
type
TMyRecord = record
Data: string;
public // <- これ
/// <summary>
/// テスト関数
/// </summary>
function Test(a, b: Integer): Integer;
・連続して定義された型
たとえば、次のように型が連続して定義されていると、ドキュメントコメントがヘルプインサイトに表示されない事があるようです。
type
TMyRecord1 = record
...
TMyRecord2 = record // <- TMyRecord2 のドキュメントコメントが表示されない
...
この場合 type を挿入してやればいいようです。
type
TMyRecord1 = record
...
type // <- これ
TMyRecord2 = record
...
ライブテンプレート
XML ドキュメントコメントはライブテンプレートを使うと簡単に挿入できます。例えば summary〔Tab〕 と入力すると、
/// <summary>
///
/// </summary>
が挿入されます。
[表示 | ツールウィンドウ | テンプレート] (古いバージョンでは [表示 | テンプレート]) でテンプレートウィンドウを表示し、リストからダブルクリックする事でもテンプレートを挿入できます。
See also:
XML ドキュメントコメント関連のライブテンプレート
XML ドキュメントコメント関連のライブテンプレートには次のようなものがあります。
| テンプレート名 | 説明 |
|---|---|
| summary | XMLDoc の <summary> タグを作成します |
| param | XMLDoc の <param> タグ タグを作成します |
| returns | XMLDoc の <returns> タグを作成します |
| remarks | XMLDoc の <remarks> タグを作成します |
| para | XMLDoc の <para> タグを作成します |
See also:
ライブテンプレートの格納位置
ユーザが作成したライブテンプレートは %UserProfile%\Documents\Embarcadero\Studio\code_templates に保存されますが、この位置はライブテンプレートが利用可能なすべてのバージョンの Delphi が参照しています。よって、複数のバージョンの Delphi をインストールしている場合には、動作しないライブテンプレートが含まれてしまう可能性があります。
バージョン固有のライブテンプレートは <Delphi インストールフォルダ>\ObjRepos 以下のフォルダに保存することで、競合を解決する事が出来ます。
| 種類 | ライブテンプレートの保存場所 |
|---|---|
| 古い Delphi | <Delphi インストールフォルダ>\ObjRepos\code_templates\delphi |
| Delphi (英語 UI) | <Delphi インストールフォルダ>\ObjRepos\en\Code_Templates\Delphi |
| Delphi (日本語 UI) | <Delphi インストールフォルダ>\ObjRepos\ja\Code_Templates\Delphi |
Documentation Insight
Delphi XE2～XE5 には Documentation Insight という XML コメント入力支援ツールの Express 版がバンドルされていました。有償版は現在でも入手可能です。
See also:
- Documentation Insight (DEVJET SOFTWARE)
- Documentation Insight Express (DocWiki)
- Documentation Insight Express for RAD Studio XE5 (CodeCentral)
おわりに
活用しようとするとさまざまな要素が絡んでくる XML ドキュメントコメントですが、情報を整理してみるとそんなに難しいものではありませんね。