search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.05k stars 861 forks source link

[Bug] Metadata extracted from DLL does not include triple slash comments #10231

Open MarkStega opened 3 weeks ago

MarkStega commented 3 weeks ago

Describe the bug When I create a doc site using DocFx I get different results if I reference a DLL versus a CSPROJ. Using the DLL as a metadata source looses the '///' comments

To Reproduce Steps to reproduce the behavior:

  1. Clone the repository at BlazorBounce
  2. From the root run ServeDocs
  3. Observe the output, there are no /// comments
  4. Change the source spec to be the csproj
  5. Run ServeDocs again
  6. Observe /// comments

Expected behavior I expect the output to be the same or that documentation be added that states that /// comments aren't available when metadata is extracted from a DLL

Context (please complete the following information):

Additional context Add any other context about the problem here.

filzrev commented 3 weeks ago

When generating API metadata from DLLs. It requires documentation XML files to extract comments.

What would happen if the following lines were added to .csproj.


<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
MarkStega commented 3 weeks ago

@filzrev

That works, however:

1) Why does specifying the csproj as input work without having that entry?

2) This 'hint' needs to be added to the DocFx documentation

Thanks for the help...

filzrev commented 3 weeks ago

Why does specifying the csproj as input work without having that entry?

When generating docs from csproj. docfx run code analysis to C# source code. (It's executed on memory. and DLL is no generated) So separated documentation xml files are not needed.

On the contrary, when generating docs from DLL files. docfx manually loading documentation xml files. https://github.com/dotnet/docfx/blob/4d5949af96797a34d418f3fcb6b31f63392df5de/src/Docfx.Dotnet/CompilationHelper.cs#L201C2-L201C21

MarkStega commented 2 weeks ago

@filzrev

Thanks very much for explaining the difference in the two methods.

I think all that is needed now is a minor documentation update.