dotnet / docfx

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

[Bug] Markdown Metadata Output For Generic Classes Doesn't Show Derived Section #10268

Open MarcosCosmos opened 1 month ago

MarcosCosmos commented 1 month ago

Describe the bug Not sure why, but the markdown metadata output format doesn't seem to include a Derived section on pages that happen to be generic, even though they would be listed in the yaml counterpart.

To Reproduce Steps to reproduce the behavior:

  1. Create a dummy project with a generic base class and one or more derived classes, e.g.:
    
    namespace DocFXTest;
    public class GenericBaseClass<T>
    {
    }

public class GenericDerivedClass : GenericBaseClass { }

2. Run DocFX with a minimal config for the project, i.e.:

{ "metadata": [ { "src": [ ... ], "dest": ... } ] }

4. Observe that the `derivedClasses` section is present in `DocFXTest.GenericBaseClass-1.yml:`

... derivedClasses:

Actual behavior DocFXTest.GenericBaseClass-1.md, does not have a Derived section, i.e.:

# <a id="DocFxTest_GenericBaseClass_1"></a> Class GenericBaseClass<T\>

Namespace: [DocFxTest](DocFxTest.md)  
Assembly: DocFxTest.dll

```csharp
public class GenericBaseClass<T>

Type Parameters

T

Inheritance

objectGenericBaseClass<T>

Inherited Members

object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.MemberwiseClone(), object.ReferenceEquals(object?, object?), object.ToString()



**Context (please complete the following information):**
- Docfx version: 2.77.0
- Template: markdown (api output format)

**Additional context**
The trigger condition appears to be the base class that is generic, and only that page is affected. Non-generic base classes will include a `#### Derived` section.
filzrev commented 2 weeks ago

I've also confirmed it can be reproduced when using "outputFormat": "apiPage".

It seems there is a problem on following logics. https://github.com/dotnet/docfx/blob/main/src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs#L398

When BaseType is generic class. It seems SymbolEqualityComparer.Default.Equals always returns false.

It need to compare BaseType.OriginalDefinition instance instead.