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

[Feature Request] <inheritdoc> with cref to non-base members / implemented interfaces #8443

Closed
mikernet opened this issue Feb 24, 2023 · 2 comments
Labels
dotnet: xml-comment XML comment for .NET API reference docs dotnet Generate .NET API reference docs

Comments

@mikernet
Copy link
Contributor

mikernet commented Feb 24, 2023

There are situations where I want to inheritdoc with a cref to a member that is not part of a base class or inherited interface. This works fine in VS intellisense, but docfx does not resolve those.

For example:

public interface ISomeCollection : ICollection<Thing>
{
    /// <inheritdoc cref="IReadOnlySomeCollection.GetThingById(int)"/>
    Thing GetThingById(int id);
}

public interface IReadOnlySomeCollection : IReadOnlyCollection<Thing>
{
    /// <summary
    /// Gets current a thing by id.
    /// </summary>
    Thing GetThingById(int id);
}

Is there a reason docfx limits inheritdoc to actual base classes / implemented interfaces?

@yufeih yufeih added dotnet Generate .NET API reference docs dotnet: xml-comment XML comment for .NET API reference docs labels Feb 24, 2023
@mikernet
Copy link
Contributor Author

mikernet commented Feb 28, 2023

So it looks like v2.62 does actually support this now. For some members on some classes (doesn't seem to do this on interfaces) it decides to outputs warnings like this, even though they do resolve fine, appear in the docs generated, and some of them inherit docs from interface members that they do implement:

Could not resolve base documentation for 'Singulink.Collections.Map`2.Add(`0,`1)'
Could not resolve base documentation for 'Singulink.Collections.HashSetDictionary`2.ContainsKey(`0)'
Could not resolve base documentation for 'Singulink.Collections.HashSetDictionary`2.KeyCollection.Contains(`0)'
Could not resolve base documentation for 'Singulink.Collections.HashSetDictionary`2.ValueCollection.Contains(`1)'
Could not resolve base documentation for 'Singulink.Collections.HashSetDictionary`2.ValueCollection.Count'
Could not resolve base documentation for 'Singulink.Collections.HashSetDictionary`2.ValueCollection.Count'
Could not resolve base documentation for 'Singulink.Collections.ListDictionary`2.ContainsKey(`0)'
Could not resolve base documentation for 'Singulink.Collections.ListDictionary`2.KeyCollection.Contains(`0)'

There doesn't appear to be any rhyme or reason as to what warns and what doesn't. For example, Map.Add implements IMap.Add but shows up in the warnings above:

image

Other Map members that do exactly the same thing do not show any warnings, i.e. Map.Contains implements IMap.Contains exactly the same way:

image

Map.LeftValues does not actually implement IMap.LeftValues (the implementation for that is explicit) but does not appear in any warnings:

image

All the inheritdocs appear to work fine though.

@mikernet
Copy link
Contributor Author

mikernet commented Mar 4, 2023

Nevermind - it works when you reference the .dll files as the metadata.src.files in docfx.json, but it does not work when you reference the .csproj files and try to generate docs from source, and unfortunately referencing .dll files means you lose the view source links.

None of the above examples work when referencing the csproj.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dotnet: xml-comment XML comment for .NET API reference docs dotnet Generate .NET API reference docs
Projects
None yet
Development

No branches or pull requests

2 participants