[Unity・C#]ソースコードからドキュメントを自動で作成する

2023年8月24日

クラス、メンバーの説明をまとめた資料をコードから作成するツールを使って自動的に設計資料を作成します

設計資料を残す必要があるケース

コードが複雑になってくると説明資料があった方がいいですね。また、その資料からどのあたりをリファクタリングすべきかの糸口を掴めることもあります。ただ、設計、コーディング前にしっかり作り込むと更新があった場合にこの資料の更新作業も大きな負担になってきます。更新が遅れるともういつの資料かもわからなくなります。
まとめると、

  • 提出物に必要とされる
  • チームで開発している
  • 設計が複雑でコード分析が困難
  • メソッドの使い方が知れればいい

などが挙げられますが、最新の資料は、コードそのものなので、都度手作業では負荷が大きいですね

使うツール

ブラウザでドキュメントを表示できるツールとしてDoxygenを使っていきます

Doxygen

次のページから、ダウンロードしましょう

Windows、Mac、Linuxがありますが、このページにアクセスするOSによって、自動的にそれぞれのOS向けがダウンロードされます

Macの場合

ダウンロードしたファイルを解凍（ダブルクリック）して実行ファイルを作成します
Ctrlを押しながら開くを選択して進めてください

Windowsの場合

インストーラを起動後、「次へ」で進めていってください

設定画面

実行すると設定画面が表示されます
それぞれ記入していくとテキストの設定ファイルが作成されます
画面はMacですがきほんWindowsでも同じです

Project設定（ドキュメント作成を１つのプロジェクトとして考えます）

表示を日本語化したい場合

追記(2022/9/4)

画面はWindows版です

WizardタブからExpertタブに変更し、Projectを選択します

privateアクセス修飾子を表示でしたい場合

追記(2022/9/4)
画面はWindows版です

WizardタブからExperタブに変更し、Projectを選択します

詳細設定ドキュメント

Mode設定

Output設定

Diagram設定

Run（実行）

Diagram設定後、Nextをクリックするとドキュメント作成実行画面になります

以降は、コードを新規作成/更新のあと、Run doxygenをクリックするだけで再度作成されます

作成されたドキュメントをブラウザで確認

以降は、コードを新規作成/更新のあと、Show HTML outputunをクリックするだけで再度作成されます

設定情報の保存

設定情報の保存

作成した設定情報は、保存したり読み出したりして使えます
実体はテキストファイルなのでメモ帳でも開くことができます

画面はWinodws版です

設定情報の読み出し

作成した設定情報は、読み出して使えます
実体はテキストファイルなのでメモ帳でも開くことができます

画面はWinodws版です

次回、doxygenを起動したときにこのファイルが選択されるようにするには

今の設定情報を開始時に使うを選択します

実際の作成したもの

DoxygenSampleとしてプロジェクトを作成します

シーンの構成

プロジェクトウィンドウに新規フォルダを作成して、１つのスクリプトを作成し保存します

PlayerControllerスクリプト

ドキュメントで自動作成されるコメントの書き方

今回作成するスクリプト

using UnityEngine;

/// <summary>
/// プレイヤーをコントロールします
/// </summary>
public class PlayerController : MonoBehaviour
{
    /// <summary>
    /// ライフの値
    /// </summary>
    public int Life;

    /// <summary>
    /// 力強さ
    /// </summary>
    public int Power;

    /// <summary>
    /// ライフの最大値
    /// </summary>
    [SerializeField]
    int maxLife;

    /// <summary>
    /// 移動処理
    /// </summary>
    /// <param name="vector">移動ベクトル</param>
    public void Move(Vector3 vector)
    {

    }
}

Doxygenの設定

プロジェクト設定

Mode設定

Output設定、Diagram設定

このまま使います

設定ファイルと作成されたドキュメントの保存場所

保存

Unityプロジェクト内に保存されます（DoxygenのProject設定）

作成されたドキュメントの確認

DiagramsメニューのRunメニューで、Show HTML outputボタンをクリックします

ブラウザが表示されます

リストの一覧

元はこれですね

/// <summary>
/// プレイヤーをコントロールします
/// </summary>
public class PlayerController : MonoBehaviour

リストからクラスを選択するとページが変わります
private変数は表示対象にならないです
ドキュメントには不要ですね

日本語表示の場合(Windows版)

追記(2022/9/4)
上記サンプルのコードではありません

ソースコードのxx行目と説明しているところをクリックすると次のページが表示されます

継承関係の場合

スクリプトに継承関係を作成しましょう

スクリプト

基本クラス（今回は抽象クラスにしています）
using UnityEngine;

/// <summary>
/// プレイヤーのベースとなるクラス
/// </summary>
public abstract class PlayerBase : MonoBehaviour
{
    /// <summary>
    /// 名前
    /// </summary>
    public string Name;
}
派生クラス
using UnityEngine;

/// <summary>
/// プレイヤーをコントロールします
/// </summary>
public class PlayerController : PlayerBase
{
    /// <summary>
    /// ライフの値
    /// </summary>
    public int Life;

    /// <summary>
    /// 力強さ
    /// </summary>
    public int Power;

    /// <summary>
    /// ライフの最大値
    /// </summary>
    [SerializeField]
    int maxLife;

    /// <summary>
    /// 移動処理
    /// </summary>
    /// <param name="vector">移動ベクトル</param>
    public void Move(Vector3 vector)
    {

    }
}

ドキュメント表示

開発、デバックの時のおすすめ設定

詳細な情報が表示される設定になります
開発中のプロジェクトフォルダにコピーして、次の項目を変更して使いましょう

デバッグ用設定

doxygenDebugダウンロード

変更箇所

Gitで管理している場合

.ignoreに次を追加します

スマホで使えるJoyStick

参考

日本語マニュアル

資料

C#,Unity,ツール,便利機能,学習,設計

Posted by hidepon