目次

キーワード

概要

ライブラリなどを作成し、公開する場合、ライブラリの内容を他人に理解してもらえるようにドキュメントを作成してやる必要があります。 ところが、プログラムのドキュメントを書く作業というのは結構面倒な作業です。 少しでも面倒な作業を減らせるように、C#コンパイラはC#のソースファイルをコンパイルする際に、一緒にXML形式のドキュメントを作成してくれます。

Javaをご存知の方はJavaのソースからドキュメントを生成するためのツール「javadoc」を使ったことがあるかもしれません。 C#のXML Documentationはこのjavadocと似たようなものです。 javadocとの違いは、コンパイラと別のツールとして提供されているのではなく、C#のXML DocumentationはC#コンパイラ自身に組み込まれていることと、出力形式がHTMLではなく、XMLであることです。

ポイント

  • /// から始まるコメントは、ソースコードからドキュメントを生成するための特別なコメントになります。

  • 要するに、C#は、javadoc のような機能を標準で持っています。

    • 標準なので、コンパイラのチェックがかかります。

    • Visual Studio の支援を受けながら書くことができます。

XML Documentの例

XML Documentを理解するために、まずは実際にXML Documentを作成してみましょう。 以下のようなソースファイルをdoctest.csという名前で作成して見てください。

using System;
using System.Collections;

namespace DocumentTest
{
  /// <summary>
  /// 簡単なサンプルとして、リストを実装する。
  /// 片方向リストで、リストに値を加えることは出来るけど、削除は出来ない。
  /// </summary>
  public class List : IEnumerable
  {
    // リストのノード
    internal class Node
    {
      public object obj;
      public Node next;

      public Node(Node next)
      {
        this.next = next;
        this.obj = null;
      }

      public Node(Node next, object obj)
      {
        this.next = next;
        this.obj = obj;
      }
    }// Node

    // リストのEnumerator
    private class ListEnumrator : IEnumerator
    {
      public ListEnumrator(List list)
      {
        this.list = list;
        current = list.head;
      }

      public bool MoveNext()
      {
        current = current.next;
        return current != null;
      }

      public object Current
      {
        get{return current.obj;}
        set{current.obj = value;}
      }

      public void Reset()
      {
        current = this.list.head;
      }

      List list;
      Node current;
    }// ListEnumerator

    /// <summary>
    /// リストの作成
    /// </summary>
    public List()
    {
      head = new Node(null);
      tail = head;
    }

    /// <summary>
    /// リストに値を加える。
    /// </summary>
    /// <param name="obj">加えたい値</param>
    public void Add(object obj)
    {
      tail.next = new Node(null, obj);
      tail = tail.next;
    }

    /// <summary>
    /// リストのEnumeratorを返す
    /// </summary>
    /// <returns>リストのEnumerator</returns>
    public IEnumerator GetEnumerator()
    {
      return new ListEnumrator(this);
    }

    private Node head; // リストのダミーヘッダー
    private Node tail; // リストの最後尾
  }// List
}// DocumentTest

そして、以下のようなオプションを付けてコンパイルしてください。 Visual C#を使って作成する場合には、プロジェクトのプロパティを開いて、「構成プロパティ」→「ビルド」→「XML ドキュメント ファイル」という項目に、出力したいXMLファイルの名前を入れてビルドを行ってください。

csc /out:DocumentTest.dll /target:library doctest.cs /doc:doctest.xml

すると、以下のような内容のXMLファイルが生成されているはずです。

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>DocumentTest</name>
    </assembly>
    <members>
        <member name="T:DocumentTest.List">
            <summary>
            簡単なサンプルとして、リストを実装する。
            片方向リストで、リストに値を加えることは出来るけど、削除は出来ない。
            </summary>
        </member>
        <member name="M:DocumentTest.List.#ctor">
            <summary>
            リストの作成
            </summary>
        </member>
        <member name="M:DocumentTest.List.Add(System.Object)">
            <summary>
            リストに値を加える。
            </summary>
            <param name="obj">加えたい値</param>
        </member>
        <member name="M:DocumentTest.List.GetEnumerator">
            <summary>
            リストのEnumeratorを返す
            </summary>
            <returns>リストのEnumerator</returns>
        </member>
    </members>
</doc>

このように、C#コンパイラでは /doc オプションを指定してやることによって、ソースファイルからXML形式のドキュメントを自動で生成することが出来ます。

Documentation Comment

上述のサンプル中には、/// というように、 / 3つで始まるコメントがあります。 C#では、この /// で始まるコメントは特別な意味を持ち、ドキュメンテーションコメントと呼ばれています。 クラスやメソッドの前にこのドキュメンテーションコメントを入れておくと、そのクラスやメソッドに関する説明をXMLファイルに書き出してくれます。

また、C# 1.2（Visual Studio 2003 と同時期に出たバージョン）では /** コメント */ というように、 /** から始まる複数行コメントもドキュメンテーションコメントとして扱われるようになりました。

ここで、ドキュメンテーションコメントの内容はXML形式で書きます。 例えば、上述のサンプルでは<summary>というXML要素が出てきますが、この要素中には、そのクラスやメソッドの概要を書きます。 以下にドキュメンテーションコメント用のタグの一覧を示します。

タグ名 説明
<c> コード(summaryなどの文中に書くもの)
<code> コード(複数行にわたるもの)
<example> サンプル コードの説明(codeと組み合わせて使う)
<exception> 例外クラスの説明
<include> 別のファイルの内容を取り込む
<list> アイテマイズしたいときに使う
<param> そのメソッドの引数に関する説明
<paramref> summaryなどの文中で引数を参照したいときに使う
<permission> メンバーへのアクセスのパーミッションを指定する
<remarks> クラスの説明
<returns> 戻り値の説明
<see> 他のメンバーを参照したいときに使う
<seealso> 他に参照して欲しいものがあるときに使う
<summary> そのクラスやメソッドの概要
<value> プロパティの説明

更新履歴

ブログ