Unity asmdefs (assemblies) don't include method documentation in metadata

[NoTuxNoBux]

Type: Bug

Issue Description

Unity packages included through the Unity Package Manager lose their C# code documentation (e.g. for classes and methods), resulting in tooltips not showing this documentation nor thrown exceptions or other documentation.

It works fine for actual NuGet package assemblies such as Autofac if you directly include these somewhere in Assets/Scripts.

We can always open the actual file to view the documentation in Unity, but we use Roslyn analyzers that need information in the documentation such as thrown exceptions to analyze these, and without this information they can't operate correctly - as mentioned this works fine for 'real' NuGet dependencies such as Autofac.

This might well be a Unity issue instead, but I'm not sure so I thought I'd report this here first.

Screenshots

Original Triangulator.cs (Unity asmdef):

Metadata when navigating to definition:

Part of Autofac's Module.cs (NuGet package/assembly):

Metadata when navigating to definition:

Steps to Reproduce

1. In manifest.json or the Unity package manager, include com.andywiecko.burst.triangulator at 2.4.0.
2. Ensure you are also using the com.unity.ide.visualstudio package with at least version 2.0.22 so it supports VSCode C# project generation.
3. Open Library/PackageCache/com.andywiecko.burst.triangulator@2.4.0/Runtime/Triangulator.cs, observe Triangulator.Status.OK having <summary> documentation.
4. Write a C# script Assets/Scripts that refrences Triangulator.Status.OK.
5. Hover over OK and observe no tooltip being shown.
6. Perform 'Go to definition' on OK and observe the documentation not being present in the metadata.

Expected Behavior

Documentation is visible.

Actual Behavior

Documentation is not visible.

Logs

Can't include detailed logs because it seems to include a lot of file information on files and assemblies and this is a proprietary project. Not sure how relevant this is since it doesn't seem to include much information on the problem at hand, but am willing to create a reproducible project if necessary.

Environment information

VSCode version: 1.90.2 C# Extension: 2.34.12 Using OmniSharp: false

Dotnet Information

.NET SDK: Version: 8.0.301 Commit: 1a0e9c0300 Workload version: 8.0.300-manifests.f6879a9a MSBuild version: 17.10.4+10fbfbf2e Runtime Environment: OS Name: org.freedesktop.platform OS Version: 23.08 OS Platform: Linux RID: linux-x64 Base Path: /usr/lib/sdk/dotnet8/lib/sdk/8.0.301/ .NET workloads installed: There are no installed workloads to display. Host: Version: 8.0.6 Architecture: x64 Commit: 3b8b000a0e .NET SDKs installed: 8.0.301 [/usr/lib/sdk/dotnet8/lib/sdk] .NET runtimes installed: Microsoft.AspNetCore.App 8.0.6 [/usr/lib/sdk/dotnet8/lib/shared/Microsoft.AspNetCore.App] Microsoft.NETCore.App 8.0.6 [/usr/lib/sdk/dotnet8/lib/shared/Microsoft.NETCore.App] Other architectures found: None Environment variables: DOTNET_ROOT [/usr/lib/sdk/dotnet8] global.json file: Not found Learn more: https://aka.ms/dotnet/info Download .NET: https://aka.ms/dotnet/download

Visual Studio Code Extensions

|Extension|Author|Version|Folder Name| |---|---|---|---| |csdevkit|ms-dotnettools|1.7.27|ms-dotnettools.csdevkit-1.7.27-linux-x64| |csharp|ms-dotnettools|2.34.12|ms-dotnettools.csharp-2.34.12-linux-x64| |test-adapter-converter|hbenl|0.1.6|hbenl.test-adapter-converter-0.1.6-universal| |test-adapter-converter|ms-vscode|0.1.9|ms-vscode.test-adapter-converter-0.1.9| |vscode-commons|redhat|0.0.6|redhat.vscode-commons-0.0.6| |vscode-dotnet-runtime|ms-dotnettools|2.0.7|ms-dotnettools.vscode-dotnet-runtime-2.0.7| |vscode-env|IronGeek|0.1.0|irongeek.vscode-env-0.1.0| |vscode-test-explorer|hbenl|2.21.1|hbenl.vscode-test-explorer-2.21.1-universal| |vstuc|visualstudiotoolsforunity|1.0.2|visualstudiotoolsforunity.vstuc-1.0.2|

Extension version: 2.34.12 VSCodium version: VSCodium 1.90.2 (7d98c6de73fb939f1eb4b8a500c569b858b2d297, 2024-06-19T18:42:40.159Z) OS version: Linux x64 6.9.7-arch1-1.1 Modes:

[dibarbet]

@NoTuxNoBux can you let me know what the metadata file header says for each case (working vs non-working)?

e.g. at the top you should see something like

#region Assembly Aspire.Hosting, Version=9.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51
// C:\Users\dabarbet\.nuget\packages\aspire.hosting\9.0.0-preview.3.24210.17\lib\net9.0\Aspire.Hosting.dll
// Decompiled with ICSharpCode.Decompiler 8.1.1.7464
#endregion

or

#region Assembly System.Console, Version=9.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
// C:\Program Files\dotnet\packs\Microsoft.NETCore.App.Ref\9.0.0-preview.5.24306.7\ref\net9.0\System.Console.dll
#endregion

[NoTuxNoBux]

@dibarbet Sure! In the non-working case of Triangulator.cs:

#region Assembly andywiecko.BurstTriangulator, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
// /home/user/Projects/unity-project/Library/ScriptAssemblies/andywiecko.BurstTriangulator.dll
// Decompiled with ICSharpCode.Decompiler 
#endregion

In the working case of Autofac's Module.cs:

#region Assembly Autofac, Version=6.4.0.0, Culture=neutral, PublicKeyToken=17863af14b0044da
// /home/user/Projects/unity-project/Assets/Packages/NuGet/autofac/6.4.0/lib/netstandard2.1/Autofac.dll
// Decompiled with ICSharpCode.Decompiler 
#endregion

[dibarbet]

@NoTuxNoBux thanks. This might be the behavior of the decompiler we're using. If you open the dll for the non-working case /home/user/Projects/unity-project/Library/ScriptAssemblies/andywiecko.BurstTriangulator.dll in ILSpy (should be the same decompiler we use), does the type have the correct documentation there?

If the dll is something you can share, I would be happy to take a look as well. If you want to share it privately, my microsoft email is listed on my github profile (reference this issue number in the email if you could).

[NoTuxNoBux]

@dibarbet I think it should be fine to share the DLL since it's a liberally-licensed open-source project:

andywiecko.BurstTriangulator.zip

I'm on Linux, so I used Avalonia ILSpy, which indeed doesn't seem to show the documentation either:

Then again, it also doesn't do so for Autofac:

[dibarbet]

@NoTuxNoBux thanks. So the way this works for Autofac is that they include an Autofac.xml file in their nuget package with the appropriate documentation. If you download the nuget package manually and open up the archive, you can see the xml file next to the dll.

As long as the documentation file is next to the dll ILSpy should be able to find it and include it in the decompilation. That is essentially how it works in VSCode too - I assume you would find the XML documentation file next to the dll at /home/user/Projects/unity-project/Assets/Packages/NuGet/autofac/6.4.0/lib/netstandard2.1/ (where we loaded the dll to decompile).

So if you can get unity to generate the XML documentation file for the assembly and put it next to the dll then the decompiler should be able to find it. But I don't know Unity well so I can't help much with that. From a quick look there seem to be a couple threads on it which you might find useful e.g. https://forum.unity.com/threads/xml-comments-with-assembly-defintion.695203/ https://stackoverflow.com/questions/32994598/how-to-include-documentation-in-dll-to-show-method-summary-in-unity3d

[NoTuxNoBux]

@dibarbet I see, I did some more digging starting from the link you sent and the gist appears to be that the only way to get this in Unity is to trick it into generating the necessary XMLs. Unfortunately there is no official support yet despite them having had it 'on their roadmap' for several years. I also found this Unity issue that seems related but was similarly 'postponed'.

In any case, thanks for your assistance and I think this ticket can be closed since there is not much to do from the side of this project :slightly_smiling_face: .