[UE4]BPのAPIリファレンスのドキュメントを自動作成する方法

執筆バージョン: Unreal Engine 4.21

UE4 Advent Calendar 2018 19日目です。
今回はブループリントをドキュメント化するプラグインを作ったのでそれについて書きたいと思います。

作った経緯

UnrealEngineを使うようになって、イテレーションのスピードが上がったのはいいのですが、
スピードを優先にしてコメントを疎かにすることが増えたなーと感じるようになり
なんでこうなってしまったのか考えてみたのですが、コメントが自然に目に入らなくなったのが原因なのかなぁと…
c＋＋の場合はヘッダーファイルに書けば、必要な設定ファイルをテキストで書く必要があるため嫌でも目に入ります。

//
// クラスのコメント
//
class MyClass
{
public:
// コメント
// @param inValue:引数
// @return 返り値のコメント
int GetFunction(int inValue);

// クラスのコメント

class MyClass

{

public:

// コメント

// @param inValue:引数

// @return 返り値のコメント

int GetFunction(int inValue);

private:
// コメント
int hoge;
};

ブループリントからとTooltipを見る場合は、カーソルを合わせるか、

詳細ウィンドを意識的に見る必要があります。

見えないと手を抜いてしまうので、詳細を見えるようにするためにドキュメント化をしようと考えました。

ですが、テキストファイルの場合Doxygen・Javadocのように自動ドキュメント化ツールがあるのですが、
ブループリントはバイナリ形式ですので、一般的なツールを使用することができません。
探してそれっぽいものがあったのですが…

作ったほうが必要な機能を揃えれるので一から作りました。

公開場所

ソースコードをGithubに公開しました。
https://github.com/historia-Inc/BlueprintToDoc

使い方

プラグインの追加

PluginsフォルダにあるBlueprintToDocフォルダを任意のPluginsフォルダにコピーしましょう。

次にエディタ起動後にBlueprintToDocのボタンが追加されていたらOK

表示されていなければ、プラグインブラウザからプラグインを有効にしてください。

ドキュメント化の手順

エディタに追加された「BlueprintToDoc」ボタンを押してください。

ドキュメント化が終了したらダイアログが表示されます。

各種設定

ProjectSettingsのPlugins – BlueprintToDocで設定ができます。

①ドキュメントの出力フォルダの指定
※ドライブ名がなければプロジェクトからの相対パスになります。
②ドキュメント化するコンテンツフォルダ
ドキュメント化するアセットの階層を個別に指定することができます。
/Game/がContentフォルダのルートになります。
③カテゴリー名によるプロパティ
カテゴリ名をもとにプロパティをリストアップすることができます。
使用例として、調整パラメータをカテゴリ「Settings」に設定すると、
全てのブループリントの調整パラメータの一覧を作ることができます。

ドキュメントの使い方

ドキュメントの出力先にあるindex.htmlファイルを開くと作成したドキュメントを見ることができます。

①カテゴリー名によるプロパティの抽出
②ブループリント目次
クリックするすると各ブループリントの内容が右フレームに表示されます。
以下のブループリントに属するアセットはすべてドキュメント化されます。

ブループリント
マクロライブラリ
ファンクションライブラリ
ブループリントインターフェス
ウィジェットブループリント（UMG）
アニメーションブループリント

ブループリントドキュメント

①ブループリント名
②ブループリントの説明
※ブループリントの説明の設定場所
ClassSettingsを選択→BlueprintDescription の内容が表示されます。

③ディレクトリパス
④ 親クラスもしくは親ブループリント名
⑤イベント、マクロ、関数
⑥プロパティ

実装解説

プラグイン公開だけではなんですので、軽く解説していきたいと思います。

ドキュメント化の大まかな流れですが、↓のようになっています。

①AssetRegistryからブループリントオブジェクトを取得
②必要なブループリントの情報を一通り取得
※目次の作成、プロパティのカテゴリによるリストアップしたページを作成するために一度必要な情報を取得します。
③HTMLへ出力

AssetRegistryからブループリントオブジェクトを取得

AssetRegistryのGetAssets関数を利用して、AssetDataを取得することができるのですが、
今回は、FARFilterに以下条件をつけることにより、必要なアセットのみ取得しています。
・読み込むコンテンツパスの階層の指定
・UBlueprintクラスのみ

// AssetRegistryモジュールの取得
FAssetRegistryModule&amp; AssetRegistryModule = FModuleManager::LoadModuleChecked(FName("AssetRegistry"));
IAssetRegistry&amp; AssetRegistry = AssetRegistryModule.Get();

// AssetRegistryモジュールの取得

FAssetRegistryModule& AssetRegistryModule = FModuleManager::LoadModuleChecked(FName("AssetRegistry"));

IAssetRegistry& AssetRegistry = AssetRegistryModule.Get();

// 探すアセットのフィルタ
FARFilter Filter;
Filter.bRecursivePaths = true;
Filter.PackagePaths.Append(Settings->ContentPaths);
Filter.bIncludeOnlyOnDiskAssets = false;
Filter.ClassNames.Add(UBlueprint::StaticClass()->GetFName());
Filter.bRecursiveClasses = true;

// 条件にあったアセットを取得
TArray ShowAssetData;
if(!AssetRegistry.GetAssets(Filter,ShowAssetData))
{
return;
}

必要なブループリントの情報を一通り取得

ブループリントの情報を取得するためにはFAssetDataのGetAsset関数からUBlueprintクラスにキャストします。

// アセットをUBlueprintにキャスト
UBlueprint* BluprintClass = Cast(It-&gt;GetAsset());
if(BluprintClass == nullptr)
{
continue;
}

// アセットをUBlueprintにキャスト

UBlueprint* BluprintClass = Cast(It->GetAsset());

if(BluprintClass == nullptr)

{

continue;

}

イベントグラフの情報

イベント、ファンクション、マクロはUEdGraphクラスで管理されます。
UEdGraphクラスはブループリントのノードをUEdGraphNodeクラスを配列で管理してます。

Inputs・Outputsパラメータ
複数あるノードの中から、UEdGraphNodeの名前がInputsの場合は”FunctionEntry” Outputの場合 ”FunctionResult”になっているので、
それで判別してGetAllPins()関数からピンを取り出して各パラメーターの情報を取得しています。

// 入出力ピン
for(UEdGraphNode* Node : graph-&gt;Nodes)
{
bool IsFunctionEntry = (Node-&gt;GetName().Find(TEXT("FunctionEntry")) != -1);
bool IsFunctionResult = (Node-&gt;GetName().Find(TEXT("FunctionResult")) != -1);

// 入出力ピン

for(UEdGraphNode* Node : graph->Nodes)

{

bool IsFunctionEntry = (Node->GetName().Find(TEXT("FunctionEntry")) != -1);

bool IsFunctionResult = (Node->GetName().Find(TEXT("FunctionResult")) != -1);

if(IsFunctionEntry || IsFunctionResult)
{
TArray<UEdGraphPin*> AllPins = Node->GetAllPins();

for(UEdGraphPin* Pin : AllPins)
{
// ピンの情報取得
}
}
}

プロパティの情報

プロパティは以下の方法でUPropertyクラスを取得することができます。

for(TFieldIterator PropIt(BPClass); PropIt; ++PropIt)
{
UProperty* Property = *PropIt;
//　プロパティの情報取得
}

for(TFieldIterator PropIt(BPClass); PropIt; ++PropIt)

{

UProperty* Property = *PropIt;

//　プロパティの情報取得

}

ですが、親のActorクラスのプロパティが全て取得できてしまい、そのままでは表示するプロパティの情報が多くなります。、
そのため、エディタ上で追加したものだけをドキュメントにするようにしています。
エディタ上で追加したプロパティには、GetFullGroupNameで取得した名前の末に自動で”_C”がつくのでそれで判別します。

if(PropIt-&gt;GetFullGroupName(true).Right(2) == TEXT("_C"))
{
}

if(PropIt->GetFullGroupName(true).Right(2) == TEXT("_C"))

{

}

これで一通りのブループリントの情報を取得できたので、これらをもとにHTMLに出力しています。

まとめ

今回ドキュメント化のプラグインを作っての感想ですが、
ブループリントの設計が少しわかって、作ってて面白かったのが本音です。
HTMLに出力するだけで、まだドキュメント化ツールとしてはまだまだな感じですが、
あとは継承先のブループリントを見れるのでクラス図とかも作れるんじゃないカナー
もっと機能を充実させれば、設計のレビューとかに使えればイイナー
とか、願望をここに書きつつ締めたいと思います。

次はおかずさんとayumaxさんです。