docfx: `inheritdoc` fails to inherit `param`s with mismatched types

Operating System: Windows

DocFX Version Used: 2.59.3.0

Template used: default

Steps to Reproduce:

Inherit parameters from a function with the same parameter names, but different types:

    /// <summary>
    /// Create a new tween.
    /// </summary>
    /// <param name="from">The starting value.</param>
    /// <param name="to">The end value.</param>
    /// <param name="duration">Total tween duration in seconds.</param>
    /// <param name="onChange">A callback that will be invoked every time the tween value changes.</param>
    /// <returns>The newly created tween instance.</returns>
    public static Tween Tween(float from, float to, float duration, Action<float> onChange) =>
      CreateTween(from, to, duration, onChange);

    /// <inheritdoc cref="Tween" />
    public static Tween Tween(Vector2 from, Vector2 to, float duration, Action<Vector2> onChange) =>
      CreateTween(from, to, duration, onChange);

Expected Behavior:

Parameter descriptions are reused.

Actual Behavior:

Only parameters with matching types are inherited

About this issue

Original URL
State: closed
Created 2 years ago
Comments: 16 (1 by maintainers)

Most upvoted comments

It does not contains any mention of inheritdoc, it is not one of the official stuff

@paulushub, the ECMA-334 spec is many versions out of date at this point and while there is an attempt to bring it up to date (driven by https://github.com/dotnet/csharpstandard), it is missing many features that have been officially adopted in.

inheritdoc is one that is now officially recognized by the Roslyn compiler implementation and the various IDE toolings for VS and VS Code (I believe Rider as well). It may also get official inclusion by the language spec in the future. However, given that the “de facto” compiler implementation and tooling supports it, it is reasonable that docfx should as well and should mirror the relevant behavior and handling that already exists.

See https://github.com/dotnet/docfx/issues/7629 and related issues for how it should be handled. @sharwell is likely a good resource to get answers or ambiguities covered.

tannergooding on Jul 26, 2022

Seems to be here https://github.com/dotnet/docfx/blob/0341b6c0e4ec999da8cef6ac50ab720160d09c35/src/Microsoft.DocAsCode.Metadata.ManagedReference.Common/Models/SyntaxDetail.cs#L43-L56

So it requires parameter positions, names, and types to match

KalleOlaviNiemitalo on Jul 22, 2022

Okay, I think I understand what you mean. I feel that it should be possible regardless, but I’m not familiar with the internals. I’ll investigate the plugin process.

rhys-vdw on Jul 22, 2022

I see nothing in there that says that the type information of the referenced member should be considered to filter the param tags.

See the C# specs of June 2022 from Page 591: https://www.ecma-international.org/wp-content/uploads/ECMA-334_6th_edition_june_2022.pdf

It does not contains any mention of inheritdoc, it is not one of the official stuff - just like some of the tags you will see on the Microsoft site. Most of these came from NDoc and Microsoft own documentations.

You will have to rely on the tools for the implementations. DocFX is a Doc-As-Code tool and will expectedly ensure the types. Sandcastle is an XPath tool and will pick anything bearing the matching name.

Here is the summary;

DocFX will check the type, name and position of the parameter.
Sandcastle will only check the name of the parameter.

If you need the Sandcastle style, you will most likely have to write a plugin.

paulushub on Jul 22, 2022