Roslyn: CS1573 warning 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.