Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationEventAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
4
Help us understand the problem. What are the problem?

posted at

updated at

Delphi と XML ドキュメントコメント

はじめに

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 ドキュメントコメントがポップアップで表示されます。
image.png
ヘルプインサイトは

  • コードエディタでマウスポインタを識別子の上に置いてしばらく待つ。
  • 〔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 内ではヘルプインサイトが効かなかったと記憶しています。
image.png
試しに Delphi 10.4.2 で LSP を切ってみると、*.dpr でのヘルプインサイトで XML ドキュメントコメントが無視されました。
image.png
See also:

ライブテンプレート

XML ドキュメントコメントはライブテンプレートを使うと簡単に挿入できます。例えば summary〔Tab〕 と入力すると、

/// <summary>
///
/// </summary>

が挿入されます。

[表示 | ツールウィンドウ | テンプレート] (古いバージョンでは [表示 | テンプレート]) でテンプレートウィンドウを表示し、リストからダブルクリックする事でもテンプレートを挿入できます。
image.png

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 版がバンドルされていました。有償版は現在でも入手可能です。
image.png
See also:

おわりに

活用しようとするとさまざまな要素が絡んでくる XML ドキュメントコメントですが、情報を整理してみるとそんなに難しいものではありませんね。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
4
Help us understand the problem. What are the problem?