No matching documentation found for system type

[nkristek]

In my project Smaragd I started playing around with this library and I'm thinking of integrating it there. Unfortunately I'm getting some errors regarding the usage of inheritdoc on classes which subclass system types.

You can check out my current work regarding this in the feature/inheritdoc branch. This library multi-targets .NET Standard 2.0 and .NET Framework 4.5 up to 4.7.2. I'm fully aware of the issues regarding malformed .NET Standard 2.0 docs, but even when targeting .NET Framework, this construct:

/// <inheritdoc />
/// <summary>
/// This <see cref="Attribute"/> is used to indicate, that the <see cref="ViewModel.IsDirty" /> property should not be set to <see langword="true"/> when the property value changes.
/// </summary>
[AttributeUsage(AttributeTargets.Property)]
public sealed class IsDirtyIgnoredAttribute
    : Attribute
{
    // ...
}

produces the warning:
InheritDocTask warning IDT004: No matching non-duplicate nodes found for: T:NKristek.Smaragd.Attributes.IsDirtyIgnoredAttribute, which attempts to inherit from: T:System.Attribute path="node()"

I'm unsure if I'm using inheritdoc wrong (including it even though documentation is present), since in this case it won't affect the output (Attribute only declares a summary tag, which is overridden by IsDirtyIgnoredAttribute).

[saucecontrol]

Hey, thanks for the detailed report. You're correct, the warning is letting you know there was nothing valid to replace the <inheritdoc /> tag with since the base docs only include summary and you've overridden that. I guess my main question would be: why include the tag if you know it isn't going to do anything?

I would consider that an incorrect usage, although I've just realized that if you're multi-targeting, you may have one target for which the tag is valid and one for which it isn't. More commonly, I'd expect that the user intended to combine the summary tags or something like that, and the warning is there to let them know it needs another look.

[nkristek]

Thanks for your response.
At the time of writing and documenting the code there may only be a summary section on the base class.
In the future, the base class may provide a remarks section in addition to the summary section (although to be fair, the chances are pretty slim).
For example, in an update to the library, the base class gets annotated with:

<remarks>
Only use this attribute on classes inheriting from MyBaseClass.
</remarks>

I just want to make sure, that the docs are kept up to date with the one from the base class.

[saucecontrol]

Yeah, that seems reasonable. And there might be cases where the remarks appear in a newer framework but not an older one in the case of multi-targeting.

I'm hesitant to remove the warning for that because it's good for catching cases where you say this:

<inheritdoc />
<summary>My additional summary.</summary>

When you mean to say this:

<summary>
<inheritdoc path="/summary/node()" />
My additional summary.
</summary>

I guess this might be a case where if you're sure you know what you're doing, it's best to set that warning to be ignored.

[nkristek]

Thanks again for your response. As you pointed out, for my case it seems to be the best solution to set it to ignore that warning.
If I encounter anything else, I will open another issue.
Thanks.