search

dotnet / docfx

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

[Bug] Invalid cref value "!:ObservableObject" in WPF UserControl #10259

Open RobGess opened 2 days ago

RobGess commented 2 days ago

When using the ObservableObject attribute from the CommunityToolkit.Mvvm v8.3.2 package on the code behind partial class of a WPF UserControl like this:

Image

DocFx seems to have an issue with properly generating the code documentation for the SourceGenerators. The following warning occurs when generating the documention with DocFx v.2.77.0:

warning: InvalidCref: Invalid cref value "!:ObservableObject" found in XML documentation comment for SetProperty defined in CommunityToolkit.Mvvm.SourceGenerators\CommunityToolkit.Mvvm.SourceGenerators.ObservableObjectGenerator\DocFxTest.TestControl.g.cs Line 243.

I am aware that the proper way to handle this kind of functionality should utilize a view model. Also, ObservableObject used in view models don't have this issue with DocFx.

Feel free to have a look at my test project DocFxTest to reproduce this issue.

If this is an user issue and can be solve with a proper docfx.json configuration, please let me know.

Spec Summary:

Expected behavior No warning.

filzrev commented 2 days ago

Reported issue seems to be caused by CommunityToolkit.Mvvm source generator side problems.

When Roslyn failed to resolve symbol. It's resolved with !: prefixed name. And docfx reporting this name as InvalidCref warnings. https://github.com/dotnet/roslyn/blob/d5a5b2101b5ddc32adca0d7b517899607c404332/src/Compilers/CSharp/Portable/DocumentationComments/DocumentationCommentIDVisitor.cs#L86-L92

Steps to confirm root cause of problem

  1. Open DocfxTest project with Visual Studio.
  2. Open generated DocFxTest.TestControl.g.cs file from Solution Explorer.

    TreePath: [Dependencies]-[Analyzers]-[CommunityToolkit.Mvvm.SourceGenerators]-[CommunityToolkit.Mvvm.SourceGenerators.ObservableObjectGenerator]

  3. Confirm <see cref = "ObservableObject"/> symbol reference is not resolved (It's not highlighted)

How to fix problems I should be referenced by using fully qualified name. (e,g, <see cref = "global::CommunityToolkit.Mvvm.ComponentModel.ObservableObject"/>)