nakamurakko’s blog

仕事で覚えたこと、勉強したことを自分のメモ代わりに書いていこうかなと。

トップ > Delphi > Delphiのコード補完にXML ドキュメント コメントを表示したい

Delphiのコード補完にXML ドキュメント コメントを表示したい

Delphi

DelphiにはC#と同じように、クラスやメソッドなどの説明をXMLドキュメントコメントで記述できる。

XML ドキュメント コメント

例えば、クラスの説明を書けば、

/// <summary>
/// メインフォーム
/// </summary>
TMainForm = class(TForm)
end;

クラス名にカーソルを合わせるとヘルプ インサイトに表示してくれる。

f:id:nakamurakko:20200304182456p:plain

ただ、XML ドキュメント コメントを記述するためにスラッシュを3つ入力しても、XML ドキュメント コメントのテンプレートを出してくれない。(Visual Studioは出してくれる…。)

全て手書きする手間を省くため、コード補完の一覧にXML ドキュメント コメントのテンプレートを表示させてみた。

環境

  • Delphi 10.3

ライブ テンプレート作成

ライブ テンプレートを参考にしながら、テンプレートを作成した。

Delphiで「新規作成」－「その他ファイル」－「コードテンプレート」を選択。ファイル名は「XMLDocumentComment.xml」にした。保存先は「<ユーザーディレクトリー>\Documents\Embarcadero\Studio\code_templates」を選択(新規保存時にDelphiが自動的に対象ディレクトリーを表示してくれる)。

f:id:nakamurakko:20200304182515p:plain

テンプレートの内容は下記の通り。

<?xml version="1.0" encoding="utf-8" ?>
<codetemplate xmlns="http://schemas.borland.com/Delphi/2005/codetemplates"
              version="1.0.0">
    <template name="XMLDocumentComment">
        <description>
        XMLドキュメントコメント
        </description>
        <code language="Delphi" delimiter="|"><![CDATA[
/// <summary>|*|
/// </summary>
/// <param name="">
/// </param>
/// <remarks>
/// </remarks>
/// <returns>
/// </returns>
]]>
        </code>
    </template>
</codetemplate>

テンプレート名(name)は「XMLDocumentComment」。説明(description)は「XMLドキュメントコメント」。使用したい言語(language)は「Delphi」。

<![CDATA[と]]>の間にXML ドキュメント コメントを記載しているが、1行目は

/// <summary>|*|

と、テンプレートのインデントを表す特殊文字|*|を入れている。 この特殊文字を入れておくと、2行目以降を1行目と同じインデントにしてくれる。 (特殊文字を使うので、delimiter="|"も忘れずに定義しておく。)

ライブ テンプレート作成 (summaryタグだけのテンプレート)

summaryタグだけのテンプレート「XMLDocumentCommentSummaryOnly.xml」も用意した。テンプレートの内容は下記の通り。

<?xml version="1.0" encoding="utf-8" ?>
<codetemplate xmlns="http://schemas.borland.com/Delphi/2005/codetemplates"
              version="1.0.0">
    <template name="XMLDocumentCommentSummaryOnly">
        <description>
        XMLドキュメントコメント (Summaryのみ)
        </description>
        <code language="Delphi" delimiter="|"><![CDATA[
/// <summary>|*|
/// </summary>
]]>
        </code>
    </template>
</codetemplate>

テンプレート名が被らないように修正して、コメントをsummaryタグだけにした。

使ってみる

実際にCtrl+スペースなどでコード補完を呼び出してみると、一覧に作成したテンプレートが表示される。

f:id:nakamurakko:20200304182537p:plain

確定させるとXML ドキュメント コメントが追加される。

f:id:nakamurakko:20200304182557p:plain

ただ、Visual Studioのように不要なタグを省いてくれないので、適宜削除してください…。 XMLDocumentCommentSummaryOnlyの方はクラス説明用で使う時は便利だと思う。