跳到正文
zenn · 游戏开发社区· 来源· 空音·· 7 小时前AI 评分29

Unity：通过 Git URL 导入的包 summary 在 IDE 中不显示的原因及解决方法

Unity：Git URLで導入したパッケージのsummaryがIDEに表示されない原因と対処法

正文 · 原文

はじめに

こんにちは、空音です！
普段はUnityやUnreal Engineを使ってゲーム開発をしている学生です。

自作ライブラリをGit URLで別のプロジェクトに導入したところ、ソースに書いたはずのsummary（XMLドキュメントコメント）が、IDEの補完に表示されないことに気付きました。

この記事では、その原因と、表示させるための設定を紹介します。

症状

ライブラリのソースには、次のようにsummaryを書いています。

/// <summary>
/// 変更をファイルに書き込む。ファイルの書き込みは別スレッドで行う。
/// </summary>
/// <remarks>
/// 書き込みに失敗しても例外は投げず、コンソールにエラーを出して<see cref="FlushResult.Failed"/>を返す。
/// そのため、awaitせずに呼び捨てにしても、失敗に気付けなくなることはない。
/// 失敗した場合、変更は未保存のまま残り、次の呼び出しで再び書き込みを試みる。
/// </remarks>
/// <returns>書き込み結果。</returns>
public Task<FlushResult> FlushAsync();

ライブラリを開発しているプロジェクトでは、この説明が補完やマウスオーバーで表示されます。
ところが、Git URLで導入した別のプロジェクトでは、何も表示されません。

原因：パッケージが.csprojの生成対象になっていない

RiderやVisual Studioは、Unityが生成する.csprojを通して、プロジェクトのソースコードを読んでいます。

ただし、Unityはすべてのパッケージを.csprojにするわけではありません。どの種類のパッケージを.csprojにするかは設定で決まっていて、既定ではGit URLやレジストリから導入したパッケージは対象外になっています。

対象外のパッケージは、IDEから見るとビルド済みのDLLでしかありません。

対象のパッケージ
    Unity → .csprojを生成 → IDEがソースを読む → summaryが表示される

対象外のパッケージ
    Unity → DLLだけ → IDEはDLLを参照する → summaryが表示されない

summaryはDLLの中には含まれません。本来は別のXMLファイルに書き出しておく必要があるため、DLLだけを参照しているIDEには表示できないというわけです。

対処法：Git packagesを生成対象に含める

  1. Edit > Preferences（macOSはUnity > Settings）を開く
  2. External Toolsを選ぶ
  3. Generate .csproj files for:の中のGit packagesにチェックを入れる
  4. Regenerate project filesを押す

これで、Git URLで導入したパッケージのソースがIDEのソリューションに追加され、summaryが表示されるようになります。

Input Systemのように、Unityのレジストリから導入したパッケージの説明も見たい場合は、Registry packagesにもチェックを入れます。
ただし、DLLで配布されているパッケージは、この設定を有効にしてもソースが追加されないため対象外です。

定義へのジャンプも元のソースになる

この設定を有効にすると、定義へのジャンプでも、DLLから復元した内容ではなく、元のソースとコメントが開くようになります。ライブラリの中身を読みたいときにも便利です。

注意：パッケージのソースは編集しない

Git URLで導入したパッケージのソースは、プロジェクトのLibrary/PackageCacheに置かれています。
生成対象に含めるとIDEから編集できてしまいますが、ここを書き換えても、Unityによって元に戻されます。

ライブラリを修正したい場合は、ライブラリを開発しているプロジェクト（リポジトリ）のほうで編集してください。

ライブラリを公開する側にできること

この設定は利用者それぞれの環境のものなので、ライブラリ側から変えることはできません。
そこで、ライブラリのREADMEには、次のような一文を入れておくことをおすすめします。

- **IDE での説明の表示**：Git URL で導入した場合、既定ではエディタの補完に API の説明（XML ドキュメントコメント）が表示されません。`Edit > Preferences > External Tools` の `Generate .csproj files for:` で `Git packages` にチェックを入れ、`Regenerate project files` を押すと表示されます。

せっかく丁寧に書いたsummaryも、利用者のIDEに表示されなければ読んでもらえません。ライブラリを公開している方は、READMEに書いておくと親切だと思います。

おわりに

  • Unityは、既定ではGit URLやレジストリから導入したパッケージの.csprojを生成しない
  • そのためIDEはDLLだけを参照し、summaryを表示できない
  • External ToolsのGit packagesにチェックを入れ、Regenerate project filesを押すと表示される

最後まで読んでいただき、ありがとうございました！

InputとUpdate 昨日の知識を、今日の技術へ

来源：zenn · 游戏开发社区 · zenn.dev

#非AI/通用工具#Unity