Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
MarcosCosmos opened this issue Oct 16, 2024 · 1 comment
Labels
bug A bug to fix dotnet: csharp New features requires to handle C#

Comments

@MarcosCosmos
Copy link

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<T> : GenericBaseClass<T>
{
}
  1. Run DocFX with a minimal config for the project, i.e.:
{
  "metadata": [
    {
      "src": [
           ...
      ],
      "dest": ...
     }
  ]
}
  1. Observe that the derivedClasses section is present in DocFXTest.GenericBaseClass-1.yml:
...
  derivedClasses:
  - DocFxTest.GenericDerivedClass`1
...
  1. Modify the config to make the outputFormat markdown:
{
  "metadata": [
    {
      ...
      "outputFormat": "markdown"
     }
  ]
}
  1. Run DocFX again.
    Expected behavior
    One of the resulting files, DocFXTest.GenericBaseClass-1.md, should have a Derived section, i.e.:
...
#### Derived
[GenericDerivedClass<T\>](DocFxTest.GenericDerivedClass\-1.md)
...

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

[object](https://learn.microsoft.com/dotnet/api/system.object) ← 
[GenericBaseClass<T\>](DocFxTest.GenericBaseClass\-1.md)

#### Inherited Members

[object.Equals\(object?\)](https://learn.microsoft.com/dotnet/api/system.object.equals\#system\-object\-equals\(system\-object\)), 
[object.Equals\(object?, object?\)](https://learn.microsoft.com/dotnet/api/system.object.equals\#system\-object\-equals\(system\-object\-system\-object\)), 
[object.GetHashCode\(\)](https://learn.microsoft.com/dotnet/api/system.object.gethashcode), 
[object.GetType\(\)](https://learn.microsoft.com/dotnet/api/system.object.gettype), 
[object.MemberwiseClone\(\)](https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone), 
[object.ReferenceEquals\(object?, object?\)](https://learn.microsoft.com/dotnet/api/system.object.referenceequals), 
[object.ToString\(\)](https://learn.microsoft.com/dotnet/api/system.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.

@MarcosCosmos MarcosCosmos added bug A bug to fix template The stock site template labels Oct 16, 2024
@yufeih yufeih added dotnet: csharp New features requires to handle C# and removed template The stock site template labels Oct 17, 2024
@filzrev
Copy link
Contributor

filzrev commented Nov 5, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug A bug to fix dotnet: csharp New features requires to handle C#
Projects
None yet
Development

No branches or pull requests

3 participants