CS1573, CS1712 warnings shouldn't appear when inheriting docs

[AArnott]

The new <inheritdoc cref /> support is awesome. I use it now to avoid a lot of redundancy in documentation across overloads. But I found that if I document one method then inherit that doc on another method that adds just one parameter, I get a CS1573 warning when I add documentation for just the one new parameter:

Repro on sharplab. Although sharplab doesn't show the intellisense that VS does, so here is the screenshot:

The irony from the image above is that the popup when hovering over arg1 both claims that there is no documentation for that parameter while also presenting the documentation (that was inherited from the other overload).

[AArnott]

@sharwell who added the inheritdoc feature recently.

[sharwell]

The compiler doesn't actually understand inheritdoc, which is an IDE feature. I would recommend inheriting the other way around. Also, consider disabling CS1573 and using a more configurable analyzer for documentation comments.

[AArnott]

Ya, the fact that it's not in the compiler itself is a bit unfortunate, since it means when I use <inheritdoc/> it will only provide documentation to 16.4+ users. But it's still great.

I can't inherit the other way around because the method with more parameters is conditionally defined while the method with fewer parameters is always defined.

I may disable CS1573, but is there another analyzer that will still help me make sure things are adequately documented?

[jinujoseph]

It needs a cross team work between compiler and IDE

[andre-ss6]

Does this means that /// <inheritdoc /> is actually emitted in the resulting XML?

[AArnott]

Yes, @andre-ss6. The compiler does not generate xml with the docs actually copied -- it merely adds the reference. It's the language service that has to follow the refs to find the actual doc to present to the user in the editor.

[alexmg]

I have noticed the same issue with CS1573 being reported when there is a mix of include file='foo.xml' path='doc/blah/*' and direct parameter content.

[sharwell]

Moving this back to compilers. Their decision on whether CS1573 appears in this case is final in the sense that we can't override it from the IDE side.

[ZacharyPatten]

Related to #42392

• CS1591 & CS1711 & CS1734 & CS1735 not respecting inheritdoc+cref #42392 false positives on the parent of the inheritdoc
• CS1573, CS1712 warnings shouldn't appear when inheriting docs #40325 false positives on the child of the inheritdoc

Don't forget CS1712

Both CS1573 & CS1712 have the same issue. @AArnott can you add CS1712 to the title of the issue? I doubt it is necessary to open a new issue just to document CS1712 too.

Examples

/// <summary>hello world</summary>
public static class CS1573_Issue
{
	/// <summary>hello world</summary>
	/// <param name="a">hello world</param>
	public static void A(object a) { }

	/// <inheritdoc cref="A(object)"/>
	/// <param name="b">hello world</param>
	public static void B(object a, object b) { } // <- CS1573 on "a"
}

/// <summary>hello world</summary>
public static class CS1712_Issue
{
	/// <summary>hello world</summary>
	/// <typeparam name="Ta">hello world</typeparam>
	public static void A<Ta>() { }

	/// <inheritdoc cref="A{Ta}"/>
	/// <typeparam name="Tb">hello world</typeparam>
	public static void B<Ta, Tb>() { } // <- CS1712 on "Ta"
}

@sharwell

[lonix1]

And CS1734 too.

This is frustrating because I use inheritdoc+cref to reduce noise in my code, but because they don't work properly, I add lots of #pragma suppressions... which increase noise in my code! 😄

Without respecting the cref, these validators are "incomplete".

[saucecontrol]

Primary constructors are another case where inheriting partial param docs would be useful. This is now triggering CS1573: