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

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

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

正文 · AI 翻译

前言

你好，我是空音！
我是一名平时使用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