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

# はじめに 
**Delphi 10.4.2 Sydney** で XML ドキュメントコメントを書いていて **「ん？」** と思ったので記事にしてみました。

# XML ドキュメントコメント

Delphi 2007 以降では (というか Delphi 2007 以降で **"も"**) トリプルスラッシュ (`///`) で始まるコメントは **XML ドキュメントコメント**として扱われます。

例えば、このような関数があったとします。

```pascal
function Test(a, b: Integer): Integer;
begin
  result := a * b;
end;
```

`Test()` 関数の直上に次のような XML ドキュメントコメントを記述できます。

```pascal
/// <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:**

 - [XML ドキュメント コメント (DocWiki)](http://docwiki.embarcadero.com/RADStudio/ja/XML_%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88_%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88)
 - [Delphi コードの XML ドキュメント (DocWiki)](http://docwiki.embarcadero.com/RADStudio/ja/Delphi_%E3%82%B3%E3%83%BC%E3%83%89%E3%81%AE_XML_%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88)

## ヘルプインサイト

`Test()` 関数が使われている場所で**ヘルプインサイト**を表示させると、ソースコード中に記述した `Test()` 関数の XML ドキュメントコメントがポップアップで表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/21785/3c5d4aa6-4cc0-1cbb-43c7-dafab431a098.png)

ヘルプインサイトは

 - コードエディタでマウスポインタを識別子の上に置いてしばらく待つ。
 - `〔Ctrl〕+〔Shift〕+〔H〕`を押す。

いずれかの方法で表示できます。

**See also:**

 - [ヘルプ インサイト (DocWiki)](http://docwiki.embarcadero.com/RADStudio/ja/%E3%83%98%E3%83%AB%E3%83%97_%E3%82%A4%E3%83%B3%E3%82%B5%E3%82%A4%E3%83%88)

### Delphi 10.4.2 におけるヘルプインサイト

Delphi 10.4 で LSP (Language Server Protocol) が実装され、10.4.2 において \*.dpr (コンソールアプリケーションを含む Delphi プロジェクトファイル) でも LSP が正しく動作するようになった影響なのか、\*.dpr でもヘルプインサイトで XML ドキュメントコメントが使えるようになっているようです。

以前のバージョンでは \*.dpr 内ではヘルプインサイトが効かなかったと記憶しています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/21785/c27c76cc-75cb-be8c-38b1-177a58e2d736.png)

試しに Delphi 10.4.2 で LSP を切ってみると、\*.dpr でのヘルプインサイトで XML ドキュメントコメントが無視されました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/21785/ac9374f8-b4d1-2778-1dc7-b16009cd12de.png)

**See also:**

 - [コード支援機能のリファレンス (DocWiki)](http://docwiki.embarcadero.com/RADStudio/ja/%E3%82%B3%E3%83%BC%E3%83%89%E6%94%AF%E6%8F%B4%E6%A9%9F%E8%83%BD%E3%81%AE%E3%83%AA%E3%83%95%E3%82%A1%E3%83%AC%E3%83%B3%E3%82%B9)

### ドキュメントコメントがヘルプインサイトに表示されない？

記述方法によってはドキュメントコメントがヘルプインサイトに表示されない事があるようです。古い Delphi (IDE) のバグのような気がするのですが...。

#### ・可視性セクション

高度なレコード型でメソッド定義の前に **public** 等の可視性指定子がないとドキュメントコメントが表示されなかったり、最上位にあるメソッドのドキュメントコメントがそれ以降のメソッドにも表示される事があるようです。

```pascal
type
  TMyRecord = record
    Data: string;
  public // <- これ
    /// <summary>
    ///   テスト関数
    /// </summary>
    function Test(a, b: Integer): Integer;
```
  
#### ・連続して定義された型

たとえば、次のように型が連続して定義されていると、ドキュメントコメントがヘルプインサイトに表示されない事があるようです。

```pascal
type
  TMyRecord1 = record
    ...

  TMyRecord2 = record // <- TMyRecord2 のドキュメントコメントが表示されない
    ...
```

この場合 **type** を挿入してやればいいようです。

```pascal
type
  TMyRecord1 = record
    ...

type // <- これ
  TMyRecord2 = record
    ...
```

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

```pascal
/// <summary>
///
/// </summary>
```

が挿入されます。

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/21785/7ab8bc16-0f4e-7fba-f3e9-6149b4fc5474.png)

**See also:**

 - [ライブ テンプレートを使用する (DocWiki)](http://docwiki.embarcadero.com/RADStudio/ja/%E3%83%A9%E3%82%A4%E3%83%96_%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B)
 - [［テンプレート］ウィンドウ (DocWiki)](http://docwiki.embarcadero.com/RADStudio/ja/%EF%BC%BB%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%EF%BC%BD%E3%82%A6%E3%82%A3%E3%83%B3%E3%83%89%E3%82%A6)

### XML ドキュメントコメント関連のライブテンプレート
XML ドキュメントコメント関連のライブテンプレートには次のようなものがあります。

| テンプレート名 | 説明 |
|:---|:---|
| summary | XMLDoc の [&lt;summary&gt; タグ](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/summary)を作成します  |
| param | XMLDoc の [&lt;param&gt; タグ](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/param) タグを作成します  |
| returns | XMLDoc の [&lt;returns&gt; タグ](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/returns)を作成します  |
| remarks | XMLDoc の [&lt;remarks&gt; タグ](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/remarks)を作成します  |
| para | XMLDoc の [&lt;para&gt; タグ](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/para)を作成します  |

**See also:**

 - [XML documentation comments (C# programming guide) (docs.microsoft.com)](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/)

### ライブテンプレートの格納位置

ユーザが作成したライブテンプレートは `%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](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/21785/1d22f177-56c6-e54c-65a2-3037c3524237.png)
**See also:**

 - [Documentation Insight (DEVJET SOFTWARE)](https://devjetsoftware.com/products/documentation-insight/)
 - [Documentation Insight Express (DocWiki)](http://docwiki.embarcadero.com/RADStudio/XE5/ja/%E3%82%B5%E3%83%BC%E3%83%89_%E3%83%91%E3%83%BC%E3%83%86%E3%82%A3%E8%A3%BD%E3%82%A2%E3%83%89%E3%82%A4%E3%83%B3%EF%BC%88IDE_%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB%EF%BC%89#Documentation_Insight_Express)
 - [Documentation Insight Express for RAD Studio XE5 (CodeCentral)](https://cc.embarcadero.com/item/29645)

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