VisualStudioのXMLドキュメント出力
VC++の場合

2022年11月6日2022年12月7日

どもです。

大変今更ですが、つい最近VisualStudioのXMLドキュメントがC#専用ではなくVC++でも使用できる、ということ知りました。
しかし、VC++でXMLドキュメントを使用する際は、C#の場合とは異なり、少し設定が必要です。

そこで今回のエントリでは、VC++でXMLドキュメントを出力するための設定について記載します。

0. 作業環境

今回は、以下の環境で作業を行ってみます。

また今回のエントリでは、以下のようなコード、関数ヘッダ(コメントフィールド)を例に作業を進めます。

#include <iostream>

/// <summary>
/// Sample method1
/// </summary>
/// <param name="input1">Input data 1.</param>
/// <param name="input2">Input data 2.</param>
/// <returns>Sum of input1 and input2.</returns>
int method1(int input1, int input2)
{
	int output_data = 0;

	output_data = input1 + input2;

	return output_data;
}

#include <iostream>

/// <summary>
/// Sample method2
/// </summary>
/// <param name="input1">Input data 1.</param>
/// <param name="input2">Input data 2.</param>
/// <returns>Multi of input1 and input2.</returns>
int method2(int input1, int input2)
{
	int output_data = 0;

	output_data = (input1 * input2);

	return output_data;
}

1. XMLドキュメント生成の仕組み

VC++でのXMLドキュメント生成は、以下のような流れで行われます。

「はい」に設定されているファイル(.cpp)から、対応する「XDCファイル」が生成されます。
このXDCファイルは、.cppファイル毎に生成されます。

そして最後に、生成されたXDCファイルをまとめて1つのXMLファイルが生成されます。

2. XMLドキュメントの生成の設定

では、これらファイルを生成するためのVisualStudioの設定について書きます。

2.1. .cppの設定

まずは、ソースファイル(.cpp)の設定です。
「ソリューションエクスプローラ」から対応するソースファイルを選択して右クリック、「プロパティ」を選択します。

次に、表示された「プロパティページ」ダイアログにおいて、[構成プロパティ]-[C/C++]-[出力ファイル]と選択し、「XMLドキュメントファイルの生成」の項目を、「はい(/doc)」に設定します。

似たような設定項目として「XMLドキュメントファイル名」がありますが、これは(今回は)デフォルトのままにします。

この設定を、XDCファイルを出力する(したい)全てのファイルに対して行います。
(ソリューションエクスプローラ上で風数ファイルを選択して先述の手順を実施すれば、選択したファイルに対して一括での設定が可能です。)

2.2. プロジェクトの設定

次に、プロジェクトの設定です。
プロジェクトに対しては、先述の手順で生成するように設定したXDCファイルの、どれを最終的なXMLファイルに取り込むかを設定します。

設定は、「ソリューションエクスプローラ」から対応するプロジェクトを右クリック、「プロパティ」を選択します。

表示された「プロパティページ」ダイアログにおいて、[構成プロパティ]-[XML ドキュメント ジェネレーター]と選択します。
表示された画面において「追加ドキュメントファイル」に、XMLファイルに取り込みたいXDCファイルのパスを設定します。

今回の例では、「追加ドキュメントファイル」のパスに「*.xdc」と設定し、生成された全てのXDCファイルをXMLファイルに依りこむように設定しています。

3. XMLドキュメントの設定

設定が完了したので、実際にXMLファイルを生成してみます。
生成は、単にビルドを実行すればOkです。
ビルドが成功すれば、.exeファイルと同じ場所に.xmlファイルが生成されていると思います。

このファイルをテキストエディタで表示すると、以下のようになります。

<?xml version="1.0"?>
<doc>
	<assembly>
		"ConsoleApplication2"
	</assembly>
	<members>
		<member name="M:method1(System.Int32,System.Int32)">
			<summary>
Sample method1
</summary>
			<param name="input1">Input data 1.</param>
			<param name="input2">Input data 2.</param>
			<returns>Sum of input1 and input2.</returns>
		</member>
		<member name="M:method2(System.Int32,System.Int32)">
			<summary>
Sample method2
</summary>
			<param name="input1">Input data 1.</param>
			<param name="input2">Input data 2.</param>
			<returns>Sum of input1 and input2.</returns>
		</member>
	</members>
</doc>

パッと見ると、XMLのタグに対するインデントがズレてしまっていますが、大きな問題ではないので、ココではひとまず無視します。
「内容」を確認すると、ココで記載した関数ヘッダの内容が記載されていることが確認できます。

4. まとめ

今回は、VC++の関数ヘッダをXMLドキュメント生成に対応した形式で記載し、XMLドキュメントに出力するための設定内容と設定方法、および生成方法について記載しました。

実装の際には、関数ヘッダの形式/書式が問題になることがたまにあります。
その際に、後々の別形式への変換のし易さや編集のし易さを考えた場合に、この形式は都合がよいのかな、と考えます。

今回のエントリが、誰かの助けになれば幸いです。
ではっ！