LoginSignup
21
17

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

@naninunenoy(中野 洋輔)in株式会社Moff

Unityのコードコメントからドキュメントを自動生成したいならDocFXはどうでしょう

Last updated at Posted at 2019-05-14

前置きが不要な人はこちらからどうぞ。

コメントによるドキュメント生成

ソースコード内に決まった形式でコメントを残すことで、そのコメントを基にAPIリファレンスなどのwebページをドキュメントとして生成するツールがあります。

コードに書いたコメントでドキュメント(APIリファレンスなどのwebページ)まで生成できれば、APIを 作る 人用の資料をコードにコメントとして残しつつ、APIを 使う 人用の資料をwebページとしてツールで自動生成できるので、特にAPIやライブラリ、プラグイン開発者には助かるツールといえるでしょう。
明確なメリットもあってか、いろいろな開発環境に対応するツールがあります。

C#におけるドキュメント生成

C#の代表的な開発環境であるVisual Studioにてコメントのフォーマットが決められており、実質これが標準になっています。

summaryコメント例
/// <summary>
/// 関数の説明をここに書く
/// </summary>
public void DoSomething() {
  ...
}

詳細：XML コメントによるコードの文書化

また、Visual Studioでは /// と入力するだけで <summary> のxmlタグの入力を補完してくれます。

上記microsoftの記事でも解説してくれている通り、Visual Studioそのものにドキュメント生成のためのxml出力機能があります。しかし、Unityのプロジェクトに関しては勝手が違うためかxml生成ができないようで、doxygenやSandcastleを使用している人が多いようです。

DocFX

しかし、調べてみると DocFXというdotnet製のツールがあり、出力されるwebページもモダンでカッコよかったので、Unityで使用できないか試してみました。

UnityにおけるDocFX

本題です。UnityプロジェクトでDocFXからwebページを出力するための手順を以下で述べます。なお、筆者の環境は Mac / Unity2018.3 / Visual Studio 2017 です。

1.セットアップ

DocFX Getting Started

Homebrewでインストールします。

$ brew install docfx

init コマンドで出力ディレクトリを作成します

$ docfx init -q -o <ディレクトリ名>

このコマンドを打った時点でwebサイト生成のためのメタデータ群が出力ディレクトリ先に作成されます。
スクリーンショット 2019-05-13 19.32.43.png
https://github.com/naninunenoy/UnityDocFXSample/tree/master/doc

2.プロジェクトファイル(.csproj)の作成

DocFXでのドキュメント生成にはコメント付きのソースコードに加え、プロジェクトの中身を表すファイルが必要です。先の手順で作成された src/ ディレクトリ下にプロジェクトファイル(.csproj)とソースコード(.cs)を実際と同じ階層で配置する必要があります。

ここが１つのポイントなのですが、Unityで.csprojを作るには以下の条件を満たす必要があります。

  1. Unity EditorとVisual Studioを連携させること(*)
  2. 自分のプロジェクトにAssembly Definitionを定義すること

(*)もしかしたらMonoDevelopやRiderでもできるのかもしれませんが、筆者はVisual Studioしか使った経験がないので未確認です 。

UnityをVisual Studioと連携させれば.slnファイルは作られますが、.csprojは作られません。しかし、Unity EditorからのAssembly Definitionを定義すればそれに対応する.csprojが作られるため、この仕様を利用します。

Unity EditorからプロジェクトのAssets/直下なりAssets/Scripts/なりで右クリックを押し[Create]から[Assembly Definition]を選択し、任意の名前をつけて作成します。
スクリーンショット 2019-05-13 19.48.53.png

次に新規でScriptを作成し、そのScriptをダブルクリックしてVisual Studioを起動させます。すると、Unityのプロジェクトのroot階層(Assets/の上) にAssembly Definitionにつけた名前と同じ.csprojファイルが出来上がっています。

3.ソースコードにコメントを打ち込む

Scriptに以下のようにコメントを入れます。

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using MyPlugin;

// namespaceをつけるのを忘れずに!!
namespace docfxSample {
    /// <summary>
    /// Hoge component.
    /// </summary>
    public class HogeComponent : MonoBehaviour {
        /// <summary>
        /// Start is called before the first frame update
        /// </summary>
        public void Start() { }
        /// <summary>
        /// Update is called once per frame
        /// </summary>
        public void Update() { }
    }
}

4.ドキュメント生成

2.と3.の手順で作成した.csprojと.csファイルを、1.の手順で作成したディレクトリのsrc/下にコピーします。この時、Unityプロジェクトの階層を再現する必要があるので、Assets/Scripts/ディレクトリもコピーします。(.metaはあっても邪魔にはならないはずですが、不要です)
スクリーンショット 2019-05-13 20.03.18.png

これでお膳立ては済んだので、ドキュメントのディレクトに移動し、以下のコマンドでドキュメントを生成します。

$ cd <initで作成したディレクトリ>
$ docfx metadata
$ docfx build

そうすると、_site/ というディレクトリが作られ、この配下にあるものがwebサイトの構築に必要なコンポーネントになります。その中のapi/配下にAPIリファレンスのための.htmlが生成されます。
スクリーンショット 2019-05-13 20.07.48.png

docfxSample.HogeComponent.html をダブルクリックすると

スクリーンショット 2019-05-08 16.00.52.png
　　~略~
スクリーンショット 2019-05-08 16.01.03.png

のようなページが表示されると思います。

実際のwebサイトのように見たければ

$ docfx --serve

のコマンドを打って、http://localhost:8080 にブラウザからアクセスすれば見られます。

4.1 Inherited Members長すぎ問題

折角作られたページですが、継承を全て網羅しているためMonoBehaviourの派生クラスではInherited Membersがものすごく長いです。しかも折りたたんだりできません。これに対処するにはfilter機能を導入する必要があります。

Filter inherited members?
リンク先のissueで説明してくれていますが、実際に使うには結構言葉足らずです。

手順1 ドキュメント出力ディレクトリの直下にfilterConfig.ymlを作成します

filterConfig.ymlの例
apiRules:
- exclude:
    uidRegex: ^System\.Object
    type: Type
- exclude:
    uidRegex: ^UnityEngine\.Object
    type: Type
- exclude:
    uidRegex: ^UnityEngine\.Component
    type: Type
- exclude:
    uidRegex: ^UnityEngine\.Behaviour
    type: Type
- exclude:
    uidRegex: ^UnityEngine\.MonoBehaviour
    type: Type

手順2 docfx.json に以下のようにfilterの記述を追加

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "src/**.csproj"
          ],
          "exclude": [
            "**/bin/**",
            "**/obj/**"
          ]
        }
      ],
      "dest": "obj/api",
      "filter": "filterConfig.yml" // この記述を追加
    }
  ]
}

手順3 metadata作成時に--filterオプションを付与

$ docfx metadata --filter filterConfig.yml

(これ書くなら手順2は要らなくない?🤔)

こうしてdocfx build すればこんな感じにスッキリします。
スクリーンショット 2019-05-08 16.40.51.png

5.色々試す

Unityの特殊フォルダであるPlugin/下に別のAssembly Definitionを追加したり、namespaceいじってみたり、2バイト文字やemojiを入れてみたりしました。

Github Pagesで載せたのでサンプルをご覧ください←ヘッダの[Api Documentation]から移動してください。

試した結果以下のことがわかりました。

  • publicのフィールド/プロパティ/メソッドのみ反映される
  • namespaceが未設定でglobal::だと反映されない
  • namespaceごとに新たなページができる
  • 2バイト文字もemojiも表示できる
    　　スクリーンショット 2019-05-08 16.02.34.png

しかし、毎回.csprojを更新したり、.csファイルを階層ごとにコピーするのは手間なので、shellやUnityのPostProcessで自動化を試みる工夫が欲しくなるでしょう。
あと、Assembly Definitionなしでも使える術をご存知の方がいれば是非教えてください。

5.1 .gitignore

なお、gitignore/Unity.gitignoreを使っている場合、.csprojがgit管理外になってしまうので、プロジェクトのソースコードとDocFXのドキュメントを一緒のリポジトリで管理したい場合はこの.gitignoreは最上段の階層に置かないように注意してください。

終わりに

ソースコードのコメントだけでモダンでいい感じのwebページが作成できました。また、サイトを作る機能も充実してそうなので、リッチなサイトも作れそうです。
自分の作ったUnityのアセットなどのライブラリのwebページを作ってみたい人は試してみて損はないと思います。👍

参考

21
17
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
21
17

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?