I have set up a few UPM packages that I pull from github. This all works great.
Each of the packages has an asmdef assembly definition, which compiles the package scripts and places them in the Library/ScriptAssemblies folder.
I have also added xml comments to all the classes in each of those assemblies, but the only way to see the comments through intellisense is if I put the generated xml comment files directly inside the Library/ScriptAssemblies folder.
The issue here is that this folder gets wiped by Unity on various occassions, one of which is project startup. In any case, I saw in many places that I should not manually place anything inside the Library folder.
My question is then how can I include xml comment files with my UPM packages so that I can see comments and documentation in intellisense? Is there a way to make Unity automatically copy these files alongside the compiled dlls?
I just posted about the exact same problem. I’ll delete my post and just bump yours. Something I’d like to add is that if you add a package locally from disk then all the xml comments do appear just not with packages from a scoped registry.
Hello,
I have tested this and it indeed works as expected when the package is directly embedded in the Packages folder of your project or when using a file reference.
It does not work properly when the package is installed in the project directly from the registry.
May I suggest to open a bug about it through the Unity Bug Reporter?
For me it happened in both Visual Studio 2017 and 2019.
I have just submitted a bug report, referencing this post, a short description and a step by step reproduction.
The bug reporter said that an error occured the first couple times I tried submitting it… but it appears that it submitted the bug multiple times (Case 1192759 Case 1192760 Case 1192761).
The difference is that local packages are considered editable and their source files are included in the generated C# project. Whatever editor you use then indexes these files, including their xml docs.
On the other hand, for read-only remote packages from an npm repository or from git, Unity compiles them and then only adds the assembly to the project. Because Unity doesn’t generate comment xml files when compiling the assemblies, there editors can’t display any documentation.
There are probably performance tradeoffs here. Generating the xml documentation files will slow down compilation to some degree and including all source files from all packages will slow down the editors.
Still, showing the documentation inline is incredibly helpful and so I hope Unity will start generating xml comments. Especially for remote packages, which don’t change often, generating the comment xml files should make little difference.
There has been no change as of the latest 2020.1.0a16 alpha.
This is a known issue that we’ll look into improving. In the meantime, you could try the following as a workaround: there is a setting “Generate all .csproj files”, under External Tools in the Preferences, which could help with this at the cost of “polluting” the solution with all those additional C# projects. This setting should be available in 2019.2 and 2019.3 with any of the VSCode, Rider or Visual Studio IDE package.
Regarding .csproj generation on 2019.3, you need to uncheck and check again “Generate all .csproj files” in Unity preferences for newly created projects.
Hi, is there any development on this issue? When can we have a fix for it? And can Unity 2019.4 have that fix too? So far I’ve been doing fine without the comments of APIs from remote packages. But I think I’m reaching the point where it will be pretty annoying. And I have no desire to “pollute” my project with a bunch of .csproj. (Because I’m using UPM to avoid that in the first place.)
Unity still does not generate XML documentation for compiled assemblies. It does however provide options to reference the package sources instead of the compiled assemblies, in which case the documentation will be picked up (and your editor will have to index more files).
Go to Preferences » External Tools and check the package types you want to generate csproj files for and thus include as sources. I think the exact options you see depend on the editor package you use and which editor you’ve selected.
Thanks! I’m aware, but given the number of packages we’re using, this adds a considerable amount of clutter to the solution file, which offsets the usability gains by added intellisense. Hoping for the actual fix
This post should be on a tutorial somewhere for UPM package authors and users. Enabling “Generate .csproj files for” Registry and Git packages is absolutely the way for documentation of UPM packages to show up in Intellisense.
No, it’s not the way. It’s just a workaround. The problem still needs an actual fix. Because libraries provided via Nuget (prebuilt .DLLs) don’t need a .csproj to show you their API documentation.
