CS1591 & CS1711 & CS1734 & CS1735 not respecting inheritdoc+cref

[ZacharyPatten]

Topic

inheritdoc supports cref so that you can inherit the documentation of specific members, but CS1591 & CS1711 & CS1734 & CS1735 are triggering when you have them on members designed to be used with inheritdoc in the same assembly.

Possible Resolution

It might be a good idea to check for inheritdoc in the same assembly before firing CS1591 & CS1711 & CS1734 & CS1735.

Example

using System;
class Class
{
#pragma warning disable CS1711 // XML comment has a typeparam tag, but there is no type parameter by that name
#pragma warning disable CS1572 // XML comment has a param tag, but there is no parameter by that name
#pragma warning disable CS1734 // XML comment has a paramref tag, but there is no parameter by that name
#pragma warning disable CS1735 // XML comment has a typeparamref tag, but there is no type parameter by that name
	/// <summary>Documentation <paramref name="a"/> <typeparamref name="A"/>.</summary>
	/// <typeparam name="A">Documentation.</typeparam>
	/// <param name="a">Documentation.</param>
	/// <param name="b">Documentation.</param>
	/// <param name="c">Documentation.</param>
	/// <returns>Documentation.</returns>
	[Obsolete("This method is for documentation only.", true)]
	internal static void Method_XML() => throw new Exception("This method is for documentation only.");
#pragma warning restore CS1735 // XML comment has a typeparamref tag, but there is no type parameter by that name
#pragma warning restore CS1734 // XML comment has a paramref tag, but there is no parameter by that name
#pragma warning restore CS1572 // XML comment has a param tag, but there is no parameter by that name
#pragma warning restore CS1711 // XML comment has a typeparam tag, but there is no type parameter by that name
	/// <inheritdoc cref="Method_XML"/>
	public static void Method() => throw new NotImplementedException();
	/// <inheritdoc cref="Method_XML"/>
	public static void Method(int a) => throw new NotImplementedException();
	/// <inheritdoc cref="Method_XML"/>
	public static void Method<A>() => throw new NotImplementedException();
	/// <inheritdoc cref="Method_XML"/>
	public static void Method<A>(A a) => throw new NotImplementedException();
	/// <inheritdoc cref="Method_XML"/>
	public static void Method(int a, int b) => throw new NotImplementedException();
	/// <inheritdoc cref="Method_XML"/>
	public static int Method(int a, float c) => throw new NotImplementedException();
}

Example 2

Here is some of my code where I am using this pattern if it helps:
https://github.com/ZacharyPatten/Towel/blob/ab53ccda326b953432eb6a1881115a7d9d518c73/Sources/Towel/Sort.cs#L11

Alternative Possible Resolution

If there was a way to create a hidden (non-compiled, but included in XML) member in code that could be linked via cref so you didn't have to make a full compiled code member... that would likely be the ideal scenario, and this issue could be handled if that feature ever existed.

/// <summary>Documentation.</summary>
hidden MyMethodXml;
/// <inheritdoc cref="MyMethodXml"/>
void MyMethod() { }

[ZacharyPatten]

@sharwell Btw... Love this feature (inheritdoc+cref)

[sharwell]

Moving to @dotnet/roslyn-compiler. We don't have control over these warnings in the IDE layers.

[ZacharyPatten]

Related to #40325

• 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

Sorry for the duplicate comment, but I wanted don't want people to miss this if they only view one or the other.

[sharwell]

#pragma warning disable CS1711 // XML comment has a typeparam tag, but there is no type parameter by that name
#pragma warning disable CS1572 // XML comment has a param tag, but there is no parameter by that name
#pragma warning disable CS1734 // XML comment has a paramref tag, but there is no parameter by that name
#pragma warning disable CS1735 // XML comment has a typeparamref tag, but there is no type parameter by that name

I would not expect any of these diagnostics to be considered by inheritdoc. If you want to use one primary method to document other overloads, the documentation should be placed on the overload with the most parameters, and should only include the documentation for the actual elements that appear in that signature.

[ZacharyPatten]

#pragma warning disable CS1711 // XML comment has a typeparam tag, but there is no type parameter by that name
#pragma warning disable CS1572 // XML comment has a param tag, but there is no parameter by that name
#pragma warning disable CS1734 // XML comment has a paramref tag, but there is no parameter by that name
#pragma warning disable CS1735 // XML comment has a typeparamref tag, but there is no type parameter by that name

I would not expect any of these diagnostics to be considered by inheritdoc. If you want to use one primary method to document other overloads, the documentation should be placed on the overload with the most parameters, and should only include the documentation for the actual elements that appear in that signature.

I very much disagree

Unfortunately that just isn't the ideal solution. If you do that you will end up with a spider web of inheritdoc that is riddled with duplicates and hard to maintain. Having a single source of documentation for all similar methods is just better.

[sharwell]

Since you're using a documentation pattern that deviates quite substantially from the original language rules, it probably makes sense to either 1) disable the compiler diagnostics and write your own set of analyzers that cover the functionality or 2) write a diagnostic suppressor that understands the coding patterns you are using and suppresses the compiler diagnostics at the locations where you would consider them false positives.

Note that this isn't a statement about "right way" or "wrong way". I'm just saying you'll be waiting a long time if you want the compiler to have built-in understanding of this scenario because we don't even have a plan for some of the other diagnostics that are higher on the list for inheritdoc scenarios and even those have been on the backlog for years.