Unable to fetch XML Documentation from symbol a member of a custom Assembly that has a XML documentation file.

[msbasanth]

Version Used:
Visul Studio 2017 v15.5
Roslyn v2.3.0
.Net Standard v1.3

Steps to Reproduce:

1. Created an provider assembly with XML documentation generated as .xml
2. Referenced this assembly in consumer project.
3. I added an analyzer to consumer project for analyzing XML Documentation of the provider assembly.
   Analyzer analyses member access syntax node - context.RegisterSyntaxNodeAction(Analyze, SyntaxKind.SimpleMemberAccessExpression).
   And then access symbol to retrieve the XML Documentation in the called method symbol.
4. Tried getting leading trivia using symbol.DeclaringSyntaxReferences

var symbolDeclarationSyntaxNode = symbol.DeclaringSyntaxReferences.FirstOrDefault()?.GetSyntax();
var leadingTrivia = symbolDeclarationSyntaxNode.GetLeadingTrivia();

Unable to retrieve syntax using this approach to access leading trivia. It looks like syntax infrormation is not available to the compilation.

5. Tried accessing symbol.GetDocumentationCommentXml() but it always returns string.Empty.
   How can I get the XML Documentation generated for provider assembly here in consumer compilation?
   Do I need to do anything additional to get documentation available through ISymbol.GetDocumentationCommentXml()?

Expected Behavior:
ISymbol.GetDocumentationCommentXml() gives the XML documentation as in the XML DOcumentation file.

Actual Behavior:
ISymbol.GetDocumentationCommentXml() always returns string.Empty.

Please suggest how can I retrieve XML Documentation from the symbol of another assembly with XML Documentation file.

Thanks
Basanth

[msbasanth]

I personally feel XmlDocumentationProvider is very much valid for custom analyzers, with which you can provide XML documentation even for symbols from a custom assembly referenced. i.e. by making API ISymbol.GetDocumentationCommentXml() valid even for custom assemblies which provides XML Documentation externally.

[sharwell]

ISymbol.GetDocumentationCommentXml() gives the XML documentation as in the XML DOcumentation file.

I agree with this.

[sharwell]

This is going to block the ability to implement analyzers like DotNetAnalyzers/DocumentationAnalyzers#16.

[gafter]

I don't think XML documentation is loaded by the compiler for metadata references. If I'm right, this would be a feature request to start loading them. Marking as Investigation Required to determine the scope of the work needed to satisfy this request.

[sharwell]

@gafter For the analyzer testing library, we use the following code to construct a MetadataReference from file with its documentation attached:

https://github.com/dotnet/roslyn-sdk/blob/66b2eb24a0e1e8fe31ff777a8255ceecbcbddb51/src/Microsoft.CodeAnalysis.Testing/Microsoft.CodeAnalysis.Analyzer.Testing/MetadataReferences.cs

It will likely be simpler in current versions of Roslyn and/or in the compiler, since reflection would not be necessary to access these types/methods.

[lukewis]

Could someone explain to me what a "metadata reference" is? Basically I can't figure out if what I'm trying to do is supported or not, and if not, if it falls into the same category as this feature request. If my scenario is different, I'm happy to open a new issue.

My scenario is as follows:

• Generator.csproj (contains my source generator)
• AssemblyA.csproj (contains the ISymbol in question)
• AssemblyB.csproj (references AssemblyA.csproj and Generator.csproj)

Whenever I attempt to get the XMLDocs from an ISymbol in AssemblyA, it returns an empty string. I was surprised, because I thought that xmldocs should be returned if the compiler has access to the source code (I wouldn't necessarily expect xml docs to be available if I reference a dll instead of a csproj).

[sharwell]

@lukewis your scenario is the same scenario as this issue

[jezzsantos]

Hi Sam @sharwell,

Are you able to give us any help on resolving or working around this?

I have the same issue with a source generator that is added (as a ProjectReference) to ProjectA , but is trying to read the XML documentation of a ISymbol that exists in ProjectB - where ProjectA references the type in ProjectB.

We have: <GenerateDocumentationFile>true</GenerateDocumentationFile> for all projects in the solution. and I have confirmed that all assembly.xml files are in the output directory of all projects (i.e. ProjectB.xml is in the output directory of ProjectA)

But the source generator always returns null for ISymbol.DeclaringSyntaxReferences.Select(x => x.GetSyntax()).

If there is a way to explicitly add the assembly.xml files somehow to the GeneratorExecutionContext of the source generator? Could you indicate how we would do that please?

[sharwell]

@jezzsantos I'm not aware of any workarounds for this currently. XML documentation comments are not available for symbols defined in metadata during command line compilation scenarios, which includes both analyzers and source generators.

But the source generator always returns null for DeclaringSyntaxReferences

Syntax is not available for symbols defined outside the current project (including cases where the symbol is defined in a different project in the same solution).

[jezzsantos]

Thanks @sharwell. Understood. Have found an alternative approach with custom OperationFilters