[Unity・C#]ソースコードからドキュメントを自動で作成する
クラス、メンバーの説明をまとめた資料をコードから作成するツールを使って自動的に設計資料を作成します
設計資料を残す必要があるケース
コードが複雑になってくると説明資料があった方がいいですね。また、その資料からどのあたりをリファクタリングすべきかの糸口を掴めることもあります。ただ、設計、コーディング前にしっかり作り込むと更新があった場合にこの資料の更新作業も大きな負担になってきます。更新が遅れるともういつの資料かもわからなくなります。
まとめると、
- 提出物に必要とされる
- チームで開発している
- 設計が複雑でコード分析が困難
- メソッドの使い方が知れればいい
などが挙げられますが、最新の資料は、コードそのものなので、都度手作業では負荷が大きいですね
使うツール
ブラウザでドキュメントを表示できるツールとしてDoxygenを使っていきます
Doxygen
次のページから、ダウンロードしましょう
Windows、Mac、Linuxがありますが、このページにアクセスするOSによって、自動的にそれぞれのOS向けがダウンロードされます

Macの場合
ダウンロードしたファイルを解凍(ダブルクリック)して実行ファイルを作成します
Ctrlを押しながら開くを選択して進めてください
Windowsの場合
インストーラを起動後、「次へ」で進めていってください
設定画面
実行すると設定画面が表示されます
それぞれ記入していくとテキストの設定ファイルが作成されます
画面はMacですがきほんWindowsでも同じです
Project設定(ドキュメント作成を1つのプロジェクトとして考えます)

表示を日本語化したい場合
追記(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としてプロジェクトを作成します
シーンの構成
プロジェクトウィンドウに新規フォルダを作成して、1つのスクリプトを作成し保存します

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)
{
}
}
ドキュメント表示

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

Gitで管理している場合
.ignoreに次を追加します

ディスカッション
コメント一覧
まだ、コメントがありません