I’m using SourceGenerators for a custom Node framework, and i’ve been wanting to provide the Documentation from members that are auto-generated from both referenced .dll’s (UnityEngine.dll, mscorlib.dll etc) and embedded AssemblyDefinitionFiles.
When parsing ISymbol’s, the method GetDocumentationCommentXml() always returns an empty string.
For what i’ve been able to figure out, the .xml files should be provided to the SourceGenerator, and I believe this could typically be done by using the xml tag <GenerateDocumentationFile>true</GenerationDocumentationFile> in the “.csproj”. But im guessing the Unity pipeline is not doing this.
If I inspect the ParseOptions provided to the generator, i can see that the DocumentationMode is set to DocumentationMode.None.
Manually modifying the “.csproj” (or using the OnGeneratedCSProject(string path, string contents)) is not doing the trick. But modifying a “csc.rsp” file with -doc:true flag did the trick and now im getting DocumentationMode.Diagnose (i would prefer just DocumentationMode.Parse, to avoid unwanted diagnostics, but at least im getting something).
However, i still get nothing from the GetDocumentationCommentXml().
When generating code for an assembly with the source code included (assemblies in Packages or Assets), i could technically get it by inspecting the SyntaxNodes, but this is not available for external .dlls, or even the UnityEngine modules dll’s
Is there currently any way to force Unity to provide the .xml to the SourceGenerator? Or maybe i’m doing something wrong?
Okay, further investigation revealed that i was wrong on 2 accounts:
XML Docs are included for Assemblies inside Packages or Assets that include the source code. So with those, the method GetDocumentationCommentXml() propperly returns the documentation. (i dont yet know for compiled .dlls, i hope that if you include the .xml next to them, it would also work, but i did not test it) (see this reply )
I was using the -doc flag in the csc.rsp wrong: it is meant to accept the relative path of the xml file you want to generate. In my case i believe it should’ve been “Library/ScriptAssemblies/YOUR_ASSEMBLY_NAME.xml”, but this is not required at all, as the XML docs are included anyways. (but usefull though, to know you can generate them like this)
However, im still not getting any result for ISymbols that i get from “referencedAssemblies” (retrieved from Compilation.SourceModule.ReferencedAssemblySymbols). All types&members for those return empty documentation. This is how i am getting symbols from UnityEngine.dll, mscorlib or netstandard, but maybe i should use another approach, or maybe this is a Roslyn limitation?
I thought i should post this findings while i try to resolve this, in case someone finds them helpfull
Some further info, i can see that the provided .dll’s for netstandard come from "PATH_TO_UNITY_INSTALLATION\Editor\Data\NetStandard\compat\2.1.0\shims\netstandard\ASSEMBLY_NAME.dll", and those dont seem to have their “.xml” files with them ,so i would understand no documentation included for those.
However all UnityEngine modules dll’s come from "*\Editor\Data\Managed\UnityEngine\*.dll", and those do have their .xml file.
So i would think that there should be a way for those to be included?
I was inspecting the generated code in Rider, and i was literally going crazy because I could see that my generated types where propperly reading XML docs, but i was not getting the results on Unity. This was only because Rider runs the SourceGenerator by itself, and it propperly feeds the .xml for asmdefs inside Packages or Assets when doing so.
So im back to square 1, I dont have a way to read XML documentation tags for anything.
I’ve been trying to place a .xml file (named exactly like the .dll, but with the .xml extension) in places to see if Unity would pick it up. I’ve tried in Library/ScriptAssemblies, on Packages/my_package/Runtime/ (next to the .asmdef) and even on the exact path on Library\Bee\artifacts\... where (i think) the .dll that is passed to the SourceGenerator lives.
Nothing works. So im guessing from the Unity side the .xml is just completely ignored.