Skip to content

Commit ca540f2

Browse files
sharwellsharwell
authored
Merge pull request #2447 from sharwell/relax-doc-reqs
Relax documentation requirements according to the current settings
2 parents b371a67 + f78d06e commit ca540f2

36 files changed

Lines changed: 818 additions & 268 deletions

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

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ namespace StyleCop.Analyzers.Test.DocumentationRules
66
using System.Collections.Generic;
77
using System.Threading;
88
using System.Threading.Tasks;
9-
using Microsoft.CodeAnalysis;
109
using Microsoft.CodeAnalysis.Diagnostics;
1110
using StyleCop.Analyzers.DocumentationRules;
1211
using TestHelper;
@@ -17,6 +16,8 @@ namespace StyleCop.Analyzers.Test.DocumentationRules
1716
/// </summary>
1817
public class SA1600UnitTests : DiagnosticVerifier
1918
{
19+
private string currentTestSettings;
20+
2021
[Theory]
2122
[InlineData("public string TestMember;", 15)]
2223
[InlineData("public string TestMember { get; set; }", 15)]
@@ -189,6 +190,42 @@ public async Task TestFieldWithoutDocumentationAsync()
189190
await this.TestFieldDeclarationDocumentationAsync("internal", true, false).ConfigureAwait(false);
190191
await this.TestFieldDeclarationDocumentationAsync("protected internal", true, false).ConfigureAwait(false);
191192
await this.TestFieldDeclarationDocumentationAsync("public", true, false).ConfigureAwait(false);
193+
194+
// Re-test with the 'documentPrivateElements' setting enabled (doesn't impact fields)
195+
this.currentTestSettings = @"
196+
{
197+
""settings"": {
198+
""documentationRules"": {
199+
""documentPrivateElements"": true
200+
}
201+
}
202+
}
203+
";
204+
205+
await this.TestFieldDeclarationDocumentationAsync(string.Empty, false, false).ConfigureAwait(false);
206+
await this.TestFieldDeclarationDocumentationAsync("private", false, false).ConfigureAwait(false);
207+
await this.TestFieldDeclarationDocumentationAsync("protected", true, false).ConfigureAwait(false);
208+
await this.TestFieldDeclarationDocumentationAsync("internal", true, false).ConfigureAwait(false);
209+
await this.TestFieldDeclarationDocumentationAsync("protected internal", true, false).ConfigureAwait(false);
210+
await this.TestFieldDeclarationDocumentationAsync("public", true, false).ConfigureAwait(false);
211+
212+
// Re-test with the 'documentPrivateFields' setting enabled (does impact fields)
213+
this.currentTestSettings = @"
214+
{
215+
""settings"": {
216+
""documentationRules"": {
217+
""documentPrivateFields"": true
218+
}
219+
}
220+
}
221+
";
222+
223+
await this.TestFieldDeclarationDocumentationAsync(string.Empty, true, false).ConfigureAwait(false);
224+
await this.TestFieldDeclarationDocumentationAsync("private", true, false).ConfigureAwait(false);
225+
await this.TestFieldDeclarationDocumentationAsync("protected", true, false).ConfigureAwait(false);
226+
await this.TestFieldDeclarationDocumentationAsync("internal", true, false).ConfigureAwait(false);
227+
await this.TestFieldDeclarationDocumentationAsync("protected internal", true, false).ConfigureAwait(false);
228+
await this.TestFieldDeclarationDocumentationAsync("public", true, false).ConfigureAwait(false);
192229
}
193230

194231
[Fact]
@@ -200,6 +237,42 @@ public async Task TestFieldWithDocumentationAsync()
200237
await this.TestFieldDeclarationDocumentationAsync("internal", false, true).ConfigureAwait(false);
201238
await this.TestFieldDeclarationDocumentationAsync("protected internal", false, true).ConfigureAwait(false);
202239
await this.TestFieldDeclarationDocumentationAsync("public", false, true).ConfigureAwait(false);
240+
241+
// Re-test with the 'documentPrivateElements' setting enabled (doesn't impact fields)
242+
this.currentTestSettings = @"
243+
{
244+
""settings"": {
245+
""documentationRules"": {
246+
""documentPrivateElements"": true
247+
}
248+
}
249+
}
250+
";
251+
252+
await this.TestFieldDeclarationDocumentationAsync(string.Empty, false, true).ConfigureAwait(false);
253+
await this.TestFieldDeclarationDocumentationAsync("private", false, true).ConfigureAwait(false);
254+
await this.TestFieldDeclarationDocumentationAsync("protected", false, true).ConfigureAwait(false);
255+
await this.TestFieldDeclarationDocumentationAsync("internal", false, true).ConfigureAwait(false);
256+
await this.TestFieldDeclarationDocumentationAsync("protected internal", false, true).ConfigureAwait(false);
257+
await this.TestFieldDeclarationDocumentationAsync("public", false, true).ConfigureAwait(false);
258+
259+
// Re-test with the 'documentPrivateFields' setting enabled (does impact fields)
260+
this.currentTestSettings = @"
261+
{
262+
""settings"": {
263+
""documentationRules"": {
264+
""documentPrivateFields"": true
265+
}
266+
}
267+
}
268+
";
269+
270+
await this.TestFieldDeclarationDocumentationAsync(string.Empty, false, true).ConfigureAwait(false);
271+
await this.TestFieldDeclarationDocumentationAsync("private", false, true).ConfigureAwait(false);
272+
await this.TestFieldDeclarationDocumentationAsync("protected", false, true).ConfigureAwait(false);
273+
await this.TestFieldDeclarationDocumentationAsync("internal", false, true).ConfigureAwait(false);
274+
await this.TestFieldDeclarationDocumentationAsync("protected internal", false, true).ConfigureAwait(false);
275+
await this.TestFieldDeclarationDocumentationAsync("public", false, true).ConfigureAwait(false);
203276
}
204277

205278
[Fact]
@@ -430,6 +503,11 @@ public void SomeMethod() { }
430503
await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
431504
}
432505

506+
protected override string GetSettings()
507+
{
508+
return this.currentTestSettings ?? base.GetSettings();
509+
}
510+
433511
protected override IEnumerable<DiagnosticAnalyzer> GetCSharpDiagnosticAnalyzers()
434512
{
435513
yield return new SA1600ElementsMustBeDocumented();

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

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ public class SA1601UnitTests : DiagnosticVerifier
2727
}
2828
";
2929

30+
private string currentTestSettings = TestSettings;
31+
3032
[Theory]
3133
[InlineData("class")]
3234
[InlineData("struct")]
@@ -58,6 +60,20 @@ public partial {0}
5860
DiagnosticResult expected = this.CSharpDiagnostic().WithLocation(3, 1);
5961

6062
await this.VerifyCSharpDiagnosticAsync(string.Format(testCode, typeKeyword), expected, CancellationToken.None).ConfigureAwait(false);
63+
64+
// The same situation is allowed if 'documentExposedElements' and 'documentInterfaces' is false
65+
string interfaceSettingName = typeKeyword == "interface" ? "documentInterfaces" : "ignoredProperty";
66+
this.currentTestSettings = $@"
67+
{{
68+
""settings"": {{
69+
""documentationRules"": {{
70+
""documentExposedElements"": false,
71+
""{interfaceSettingName}"": false
72+
}}
73+
}}
74+
}}
75+
";
76+
await this.VerifyCSharpDiagnosticAsync(string.Format(testCode, typeKeyword), EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
6177
}
6278

6379
[Theory]
@@ -78,6 +94,20 @@ public partial {0}
7894
DiagnosticResult expected = this.CSharpDiagnostic().WithLocation(6, 1);
7995

8096
await this.VerifyCSharpDiagnosticAsync(string.Format(testCode, typeKeyword), expected, CancellationToken.None).ConfigureAwait(false);
97+
98+
// The same situation is allowed if 'documentExposedElements' and 'documentInterfaces' is false
99+
string interfaceSettingName = typeKeyword == "interface" ? "documentInterfaces" : "ignoredProperty";
100+
this.currentTestSettings = $@"
101+
{{
102+
""settings"": {{
103+
""documentationRules"": {{
104+
""documentExposedElements"": false,
105+
""{interfaceSettingName}"": false
106+
}}
107+
}}
108+
}}
109+
";
110+
await this.VerifyCSharpDiagnosticAsync(string.Format(testCode, typeKeyword), EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
81111
}
82112

83113
[Fact]
@@ -112,6 +142,10 @@ public partial class TypeName
112142
DiagnosticResult expected = this.CSharpDiagnostic().WithLocation(7, 18);
113143

114144
await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
145+
146+
// The same situation is allowed if 'documentPrivateElements' is false (the default)
147+
this.currentTestSettings = null;
148+
await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
115149
}
116150

117151
[Fact]
@@ -132,12 +166,16 @@ public partial class TypeName
132166
DiagnosticResult expected = this.CSharpDiagnostic().WithLocation(10, 18);
133167

134168
await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
169+
170+
// The same situation is allowed if 'documentPrivateElements' is false (the default)
171+
this.currentTestSettings = null;
172+
await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
135173
}
136174

137175
/// <inheritdoc/>
138176
protected override string GetSettings()
139177
{
140-
return TestSettings;
178+
return this.currentTestSettings ?? base.GetSettings();
141179
}
142180

143181
/// <inheritdoc/>

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,21 @@ enum TypeName
4747
await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
4848
}
4949

50+
[Fact]
51+
public async Task TestNestedPrivateEnumWithoutDocumentationAsync()
52+
{
53+
var testCode = @"
54+
class ClassName
55+
{
56+
private enum TypeName
57+
{
58+
Bar
59+
}
60+
}";
61+
62+
await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
63+
}
64+
5065
[Fact]
5166
public async Task TestEnumWithEmptyDocumentationAsync()
5267
{

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

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,28 @@ public void Test() { }
207207
await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
208208
}
209209

210+
[Fact]
211+
[WorkItem(2443, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2443")]
212+
public async Task TestPrivateMethodWithoutSummaryAsync()
213+
{
214+
var testCode = @"
215+
/// <summary>
216+
///
217+
/// </summary>
218+
internal class ClassName
219+
{
220+
///
221+
private void Test1() { }
222+
223+
/**
224+
*
225+
*/
226+
private void Test2() { }
227+
}";
228+
229+
await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
230+
}
231+
210232
[Fact]
211233
public async Task TestPartialMethodWithoutDocumentationAsync()
212234
{
@@ -663,10 +685,10 @@ public async Task TestEventPropertyWithoutDocumentationAsync()
663685
public class ClassName
664686
{
665687
///
666-
event System.Action Foo { add { } remove { } }
688+
public event System.Action Foo { add { } remove { } }
667689
}";
668690

669-
DiagnosticResult expected = this.CSharpDiagnostic().WithLocation(8, 25);
691+
DiagnosticResult expected = this.CSharpDiagnostic().WithLocation(8, 32);
670692

671693
await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
672694
}

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

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,18 @@ namespace StyleCop.Analyzers.Test.DocumentationRules
1818
/// </summary>
1919
public class SA1605UnitTests : DiagnosticVerifier
2020
{
21+
private const string TestSettings = @"
22+
{
23+
""settings"": {
24+
""documentationRules"": {
25+
""documentPrivateElements"": true
26+
}
27+
}
28+
}
29+
";
30+
31+
private string currentTestSettings = TestSettings;
32+
2133
[Theory]
2234
[InlineData("class")]
2335
[InlineData("struct")]
@@ -224,6 +236,32 @@ public void Test() { }
224236
await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
225237
}
226238

239+
[Fact]
240+
[WorkItem(2450, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2450")]
241+
public async Task TestIncludedNotRequiredDocumentationWithoutSummaryAsync()
242+
{
243+
var testCode = @"
244+
/// <include file='ClassWithoutSummary.xml' path='/ClassName/*'/>
245+
public partial class ClassName
246+
{
247+
///
248+
public void Test() { }
249+
}";
250+
251+
// The situation is allowed if 'documentExposedElements' false
252+
this.currentTestSettings = @"
253+
{
254+
""settings"": {
255+
""documentationRules"": {
256+
""documentExposedElements"": false
257+
}
258+
}
259+
}
260+
";
261+
262+
await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
263+
}
264+
227265
[Fact]
228266
public async Task TestIncludedDocumentationWithInheritdocAsync()
229267
{
@@ -307,6 +345,12 @@ protected override Project ApplyCompilationOptions(Project project)
307345
return project;
308346
}
309347

348+
protected override string GetSettings()
349+
{
350+
Assert.NotNull(this.currentTestSettings);
351+
return this.currentTestSettings;
352+
}
353+
310354
protected override IEnumerable<DiagnosticAnalyzer> GetCSharpDiagnosticAnalyzers()
311355
{
312356
yield return new SA1605PartialElementDocumentationMustHaveSummary();

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -354,6 +354,31 @@ public int Property
354354
await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
355355
}
356356

357+
[Fact]
358+
[WorkItem(2451, "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2451")]
359+
public async Task TestPropertyWithoutDocumentationRequirementAsync()
360+
{
361+
var testCode = @"
362+
/// <summary>
363+
///
364+
/// </summary>
365+
public class ClassName
366+
{
367+
/// <include file='PropertyWithoutValue.xml' path='/ClassName/Property/*'/>
368+
private int Property
369+
{
370+
get;
371+
}
372+
373+
/// <summary>
374+
///
375+
/// </summary>
376+
private ClassName PropertyWithSummary { get; set; }
377+
}";
378+
379+
await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
380+
}
381+
357382
protected override Project ApplyCompilationOptions(Project project)
358383
{
359384
var resolver = new TestXmlReferenceResolver();

0 commit comments

Comments
 (0)