search

dotnet / roslyn

The Roslyn .NET compiler provides C# and Visual Basic languages with rich code analysis APIs.
https://docs.microsoft.com/dotnet/csharp/roslyn-sdk/
MIT License
19k stars 4.03k forks source link

Produce type/member level source link information in docs xml #71953

Open huangmin-ms opened 8 months ago

huangmin-ms commented 8 months ago

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 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, https://github.com/MicrosoftDocs/feedback/issues/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:

  1. Reference assemblies don't have PDBs. To work around, we decided to download the runtime package and try to find the impl assemblies there. e.g. https://www.nuget.org/packages/Microsoft.NETCore.App.Runtime.win-x64/6.0.23
  2. 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. https://github.com/dotnet/roslyn/blob/f4d47439caa0a795fd94aef4b92e19cbde0fade7/src/Dependencies/CodeAnalysis.Debugging/PortableCustomDebugInfoKinds.cs#L23 But it is not documented in https://github.com/dotnet/runtime/blob/main/docs/design/specs/PortablePdb-Metadata.md and I probably never know that without asking around.
  3. I have gone through this doc https://devblogs.microsoft.com/dotnet/go-to-definition-improvements-for-external-source-in-roslyn/ and found 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?

huangmin-ms commented 7 months ago

@tmat any update for this feature request?

Falco20019 commented 4 months ago

I would love to see this end up in docfx :)