You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For every .NET project that enabled SourceLink, the source link information will be embedded in CustomDebugInformation table of its PDB. However, this is not sufficient to build a type/member level source map without information from Document and MethodDebugInformation tables.
Background and Motivation
My team is responsible for publishing .NET and other reference docs on https://learn.microsoft.com/en-us/dotnet/api/. We have received a lot of user feedback regarding linking docs page to their GitHub source code. For example, MicrosoftDocs/feedback#3099
Currently what we have are the DLLs or NuGet packages provided by our partner teams and based on that we have figured out we can use the DLL to find its corresponding PDB and then use the information in PDB to build the source links for each type/member in the DLL.
If a type (interface/Enum etc.) doesn't have any method, then it won't be recorded in MethodDebugInformation table, Roslyn introduced a new GUID TypeDefinitionDocuments to solve this.
After a lot of researching and discussing we found that it is not as easy/straightforward as we think to generate a source map based on the PDB by ourselves. And since Roslyn has already built the logic, is it possible for the compiler to generate a source link file for us to consume?
Proposed Feature
Currently compiler will generate a documentation xml including APIs with comments. One proposal is to also include the source location for each API in it.
In our scenario, we need the source locations of all the public & protected APIs in this project. Not sure if it is ok to include them in the XML doc file, regardless of whether they actually have a comment or not. or maybe it can be achieved by a new explicit build flag?
Alternative Designs
If it cannot be produced in the docs xml file, can it be generated as a standalone file containing docCommentId and sourceLinks in it?
The text was updated successfully, but these errors were encountered:
huangmin-ms
changed the title
Produce symbol level source link information in docs xml
Produce type/member level source link information in docs xml
Feb 4, 2024
Summary
For every .NET project that enabled SourceLink, the source link information will be embedded in
CustomDebugInformation
table of its PDB. However, this is not sufficient to build a type/member level source map without information fromDocument
andMethodDebugInformation
tables.Background and Motivation
My team is responsible for publishing .NET and other reference docs on https://learn.microsoft.com/en-us/dotnet/api/. We have received a lot of user feedback regarding linking docs page to their GitHub source code. For example, MicrosoftDocs/feedback#3099
Currently what we have are the DLLs or NuGet packages provided by our partner teams and based on that we have figured out we can use the DLL to find its corresponding PDB and then use the information in PDB to build the source links for each type/member in the DLL.
During our investigation, we found:
MethodDebugInformation
table, Roslyn introduced a new GUIDTypeDefinitionDocuments
to solve this.roslyn/src/Dependencies/CodeAnalysis.Debugging/PortableCustomDebugInfoKinds.cs
Line 23 in f4d4743
Go to definition
has built most of what we want. One difference is that GTD is triggered per symbol while we need to enumerate all the symbols.After a lot of researching and discussing we found that it is not as easy/straightforward as we think to generate a source map based on the PDB by ourselves. And since Roslyn has already built the logic, is it possible for the compiler to generate a source link file for us to consume?
Proposed Feature
Currently compiler will generate a documentation xml including APIs with comments. One proposal is to also include the source location for each API in it.
In our scenario, we need the source locations of all the public & protected APIs in this project. Not sure if it is ok to include them in the XML doc file, regardless of whether they actually have a comment or not. or maybe it can be achieved by a new explicit build flag?
Alternative Designs
If it cannot be produced in the docs xml file, can it be generated as a standalone file containing docCommentId and sourceLinks in it?
The text was updated successfully, but these errors were encountered: