Skip to content

Commit bb330fc

Browse files
sharwellsharwell
committed
Do not report SA1648 for inheritdoc elements with a cref attribute
Fixes #1948
1 parent e60c596 commit bb330fc

4 files changed

Lines changed: 95 additions & 21 deletions

File tree

‎StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1648UnitTests.cs‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,20 @@ public async Task TestTypeWithEmptyBaseListAsync(string declaration)
7373
await this.VerifyCSharpDiagnosticAsync(testCode + declaration, expected, CancellationToken.None).ConfigureAwait(false);
7474
}
7575

76+
[Theory(DisplayName = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1948")]
77+
[InlineData("interface Test { }")]
78+
[InlineData("class Test { }")]
79+
[InlineData("struct Test { }")]
80+
[InlineData("enum Test { }")]
81+
[InlineData("delegate void Test ();")]
82+
public async Task TestTypeWithEmptyBaseListAndCrefAttributeAsync(string declaration)
83+
{
84+
var testCode = @"/// <inheritdoc cref=""object""/>
85+
";
86+
87+
await this.VerifyCSharpDiagnosticAsync(testCode + declaration, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
88+
}
89+
7690
[Theory]
7791
[InlineData("Test() { }")]
7892
[InlineData("void Foo() { }")]
@@ -96,6 +110,28 @@ public async Task TestMemberThatShouldNotHaveInheritDocAsync(string declaration)
96110
await this.VerifyCSharpDiagnosticAsync(string.Format(testCode, declaration), expected, CancellationToken.None).ConfigureAwait(false);
97111
}
98112

113+
[Theory(DisplayName = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1948")]
114+
[InlineData("Test() { }")]
115+
[InlineData("void Foo() { }")]
116+
[InlineData("string foo;")]
117+
[InlineData("string Foo { get; set; }")]
118+
[InlineData("string this [string f] { get { return f; } }")]
119+
[InlineData("event System.Action foo;")]
120+
[InlineData("event System.Action Foo { add { } remove { } }")]
121+
[InlineData("~Test() { }")]
122+
[InlineData("public static Test operator +(Test value) { return value; }")]
123+
[InlineData("public static explicit operator Test(int value) { return new Test(); }")]
124+
public async Task TestMemberThatShouldNotHaveInheritDocButHasCrefAttributeAsync(string declaration)
125+
{
126+
var testCode = @"class Test
127+
{{
128+
/// <inheritdoc cref=""object""></inheritdoc>
129+
{0}
130+
}}";
131+
132+
await this.VerifyCSharpDiagnosticAsync(string.Format(testCode, declaration), EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
133+
}
134+
99135
[Theory]
100136
[InlineData("public override void Foo() { }")]
101137
[InlineData("public override string Bar { get; set; }")]

‎StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1648InheritDocMustBeUsedWithInheritingClass.cs‎

Lines changed: 46 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -86,11 +86,17 @@ private static void HandleBaseTypeLikeDeclaration(SyntaxNodeAnalysisContext cont
8686
DocumentationCommentTriviaSyntax documentation = context.Node.GetDocumentationCommentTriviaSyntax();
8787

8888
XmlNodeSyntax inheritDocElement = documentation?.Content.GetFirstXmlElement(XmlCommentHelper.InheritdocXmlTag);
89+
if (inheritDocElement == null)
90+
{
91+
return;
92+
}
8993

90-
if (inheritDocElement != null)
94+
if (HasXmlCrefAttribute(inheritDocElement))
9195
{
92-
context.ReportDiagnostic(Diagnostic.Create(Descriptor, inheritDocElement.GetLocation()));
96+
return;
9397
}
98+
99+
context.ReportDiagnostic(Diagnostic.Create(Descriptor, inheritDocElement.GetLocation()));
94100
}
95101

96102
private static void HandleMemberDeclaration(SyntaxNodeAnalysisContext context)
@@ -107,27 +113,50 @@ private static void HandleMemberDeclaration(SyntaxNodeAnalysisContext context)
107113
DocumentationCommentTriviaSyntax documentation = memberSyntax.GetDocumentationCommentTriviaSyntax();
108114

109115
XmlNodeSyntax inheritDocElement = documentation?.Content.GetFirstXmlElement(XmlCommentHelper.InheritdocXmlTag);
116+
if (inheritDocElement == null)
117+
{
118+
return;
119+
}
110120

111-
if (inheritDocElement != null)
121+
if (HasXmlCrefAttribute(inheritDocElement))
112122
{
113-
ISymbol declaredSymbol = context.SemanticModel.GetDeclaredSymbol(memberSyntax, context.CancellationToken);
114-
if (declaredSymbol == null && memberSyntax.IsKind(SyntaxKind.EventFieldDeclaration))
115-
{
116-
var eventFieldDeclarationSyntax = (EventFieldDeclarationSyntax)memberSyntax;
117-
VariableDeclaratorSyntax firstVariable = eventFieldDeclarationSyntax.Declaration?.Variables.FirstOrDefault();
118-
if (firstVariable != null)
119-
{
120-
declaredSymbol = context.SemanticModel.GetDeclaredSymbol(firstVariable, context.CancellationToken);
121-
}
122-
}
123+
return;
124+
}
123125

124-
// If we don't have a declared symbol we have some kind of field declaration. A field can not override or
125-
// implement anything so we want to report a diagnostic.
126-
if (declaredSymbol == null || !NamedTypeHelpers.IsImplementingAnInterfaceMember(declaredSymbol))
126+
ISymbol declaredSymbol = context.SemanticModel.GetDeclaredSymbol(memberSyntax, context.CancellationToken);
127+
if (declaredSymbol == null && memberSyntax.IsKind(SyntaxKind.EventFieldDeclaration))
128+
{
129+
var eventFieldDeclarationSyntax = (EventFieldDeclarationSyntax)memberSyntax;
130+
VariableDeclaratorSyntax firstVariable = eventFieldDeclarationSyntax.Declaration?.Variables.FirstOrDefault();
131+
if (firstVariable != null)
127132
{
128-
context.ReportDiagnostic(Diagnostic.Create(Descriptor, inheritDocElement.GetLocation()));
133+
declaredSymbol = context.SemanticModel.GetDeclaredSymbol(firstVariable, context.CancellationToken);
129134
}
130135
}
136+
137+
// If we don't have a declared symbol we have some kind of field declaration. A field can not override or
138+
// implement anything so we want to report a diagnostic.
139+
if (declaredSymbol == null || !NamedTypeHelpers.IsImplementingAnInterfaceMember(declaredSymbol))
140+
{
141+
context.ReportDiagnostic(Diagnostic.Create(Descriptor, inheritDocElement.GetLocation()));
142+
}
143+
}
144+
145+
private static bool HasXmlCrefAttribute(XmlNodeSyntax inheritDocElement)
146+
{
147+
XmlElementSyntax xmlElementSyntax = inheritDocElement as XmlElementSyntax;
148+
if (xmlElementSyntax?.StartTag?.Attributes.Any(SyntaxKind.XmlCrefAttribute) ?? false)
149+
{
150+
return true;
151+
}
152+
153+
XmlEmptyElementSyntax xmlEmptyElementSyntax = inheritDocElement as XmlEmptyElementSyntax;
154+
if (xmlEmptyElementSyntax?.Attributes.Any(SyntaxKind.XmlCrefAttribute) ?? false)
155+
{
156+
return true;
157+
}
158+
159+
return false;
131160
}
132161
}
133162
}

‎documentation/KnownChanges.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,12 @@ public class ApiStatus
246246
}
247247
```
248248

249+
### SA1648
250+
251+
This rule has been modified to adhere more closely to the use of `<inheritdoc>` with Sandcastle Help File Builder. As a
252+
result, some code which resulted in SA1648 being reported by StyleCop Classic will no longer report this warning in
253+
StyleCop Analyzers.
254+
249255
### SA1649
250256

251257
StyleCop Analyzers modified SA1649 to check the first type against the actual file name as opposed to checking against a

‎documentation/SA1648.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,20 @@
1717

1818
## Cause
1919

20-
`<inheritdoc>` has been used on an element that doesnt inherit from a base class or implement an interface..
20+
`<inheritdoc>` has been used on an element that doesn't inherit from a base class or implement an interface.
2121

2222
## Rule description
2323

24-
Verifies that an 'inheritdoc' tag is not used when the class or interface does not inherit from a base class or interface.
24+
Verifies that an `<inheritdoc>` element is not used when the class or interface does not inherit from a base class or
25+
interface. A violation of this rule occurs when the element having the `<inheritdoc>` element doesn't inherit from a
26+
base case or implement an interface.
2527

26-
A violation of this rule occurs when the element having the inheritdoc tag doesn't inherit from a base case or implement an interface.
28+
`<inheritdoc/>` elements are always allowed when they contain a `cref` attribute, which specifies the target element
29+
from which documentation is inherited.
2730

2831
## How to fix violations
2932

30-
To fix a violation of this rule, remove the `<inheritdoc>` tag and document the element appropriately.
33+
To fix a violation of this rule, remove the `<inheritdoc>` element and document the element appropriately.
3134

3235
## How to suppress violations
3336

0 commit comments

Comments
 (0)