More than 5 years have passed since last update.

DocFXを使ってC#のソースコードからAPIのドキュメントを作成

docfx

Last updated at 2017-02-09Posted at 2017-02-09

DocFXとは

C#(というか.NET)のソースコードのコメントから、
こんな感じのドキュメントが作成できる。
ただ、スタンドアローンで使うには微妙。

環境

Windows7 Professional

インストール

githubからビルド済みバイナリを取得して展開。
Microsoft Build Tools 2015 をダウンロードしてインストール。
Node.jsをダウンロードしてインストール。

使ってみる

初期化

ビルド済みバイナリを展開すると、「docfx.exe」があるので、

docfx.exe init -q -o DocFXSample

と実行すると、「DocFXSample」ディレクトリが作成される。

C#のプロジェクトとソースファイルを用意

ここではプロジェクト名をDocFXSampleとしたので、
csprojのファイル名はDocFXSample.csprojとなる。
コメントもつけておく。

Program.cs

using System;

namespace DocFXSample
{
    /// <summary>
    /// 基底クラス。
    /// </summary>
    public class BaseClass
    {
        /// <summary>
        /// 基底クラスのメンバ。
        /// </summary>
        public int sum;

        /// <summary>
        /// 基底クラスの仮想メソッド。
        /// sumを+1して返す。
        /// </summary>
        /// <returns>sumの値</returns>
        public virtual int func()
        {
            sum++;
            return sum;
        }
    }

    /// <summary>
    /// 継承クラス。
    /// </summary>
    public class DerivedClass : BaseClass
    {
        /// <summary>
        /// 仮想メソッド。
        /// 基底クラスと異なりsumを+2して返す。
        /// </summary>
        /// <returns>sumの値(derived)</returns>
        public override int func()
        {
            sum++;
            sum++;
            return sum;
        }
    }

    /// <summary>
    /// enumのテスト。
    /// </summary>
    public enum EnumTest
    {
        /// <summary>
        /// 要素1。
        /// </summary>
        Elem1,
        /// <summary>
        /// 要素2。
        /// </summary>
        Elem2,
        /// <summary>
        /// 要素3。
        /// </summary>
        Elem3,
    }
    /// <summary>
    /// enumの拡張メソッドテスト。
    /// </summary>
    public static class EnumTestExt
    {
        /// <summary>
        /// EnumTest.Nameの拡張メソッド。
        /// </summary>
        /// <param name="value">EnumTest。</param>
        /// <returns>EnumTestの値に応じた文字列。</returns>
        public static string Name(this EnumTest value)
        {
            switch (value)
            {
                case EnumTest.Elem1: return "要素1。";
                case EnumTest.Elem2: return "要素2。";
                case EnumTest.Elem3: return "要素3。";
            }
            return "不明。";
        }
    }

    /// <summary>
    /// 実行クラス。
    /// </summary>
    public class Program
    {
        /// <summary>
        /// エントリーポイント
        /// </summary>
        /// <param name="args">引数</param>
        static void Main(string[] args)
        {
            BaseClass b = new BaseClass();
            DerivedClass d = new DerivedClass();
            EnumTest e = EnumTest.Elem1;

            Console.WriteLine("開始。");
            Console.WriteLine("BaseClass     = {0}", b.func());
            Console.WriteLine("DerivedClass  = {0}", d.func());
            Console.WriteLine("EnumTest.Name = {0}", e.Name());
            Console.WriteLine("終了。");
        }
    }
}

作成したC#プロジェクトとソースファイルを docfx/DocFXSample/src へコピーする。

以下のような感じ。

C:\work\docfx\DocFXSample
│  .gitignore
│  docfx.json
│  index.md
│  toc.yml
│
├─api
│      .gitignore
│      index.md
│      toc.yml
│
├─apidoc
├─articles
│      intro.md
│      toc.yml
│
├─images
└─src
        DocFXSample.csproj ← 追加
        Program.cs         ← 追加