Add code fixes for documentation diagnostics (#1) by jgefen · Pull Request #3445 · DotNetAnalyzers/StyleCopAnalyzers

jgefen · 2022-01-27T14:16:17Z

Add helpers
Add documenation fix SA1600 for most types
Add SA1611 codefix
Add SA1602 codefix
Add SA1618 codefix

Co-authored-by: Alon Sheffer alon.sheffer@intel.com
Co-authored-by: Jonatan Gefen jonatan.gefen@intel.com

* Add helpers * Add documenation fix SA1600 for most types * Add SA1611 codefix * Add SA1602 codefix * Add SA1618 codefix Co-authored-by: Alon Sheffer <alon.sheffer@intel.com> Co-authored-by: Jonatan Gefen <jonatan.gefen@intel.com>

Style fixes

codecov · 2022-01-27T15:14:11Z

Codecov Report

Merging #3445 (6332dea) into master (a821966) will decrease coverage by 0.00%.
The diff coverage is 93.26%.

❗ Current head 6332dea differs from pull request most recent head 9d2d366. Consider uploading reports for the commit 9d2d366 to get more accurate results

@@            Coverage Diff             @@
##           master    #3445      +/-   ##
==========================================
- Coverage   93.17%   93.17%   -0.01%     
==========================================
  Files        1047     1058      +11     
  Lines      112348   113868    +1520     
  Branches     3976     4039      +63     
==========================================
+ Hits       104684   106100    +1416     
- Misses       6644     6711      +67     
- Partials     1020     1057      +37

sharwell · 2022-01-27T16:43:50Z

📝 Keep in mind I'll be primarily evaluating this in the context of #764 (comment). It seems likely that you'll want one or more features that don't get merged here. For that, it's possible to add a custom code fix project which recognizes diagnostics produced by StyleCop Analyzers and can provide fixes beyond the scope of this project.

sharwell · 2022-01-27T16:46:45Z

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

+enum TypeName
+{
+    /// <summary>
+    /// Bar.


📝 This isn't a meaningful addition, so the preference is to not automatically generate it. It's fine to generate the empty <summary> element, but the contents should not be automatically generated except in limited cases where a specific design pattern includes the documentation form.

sharwell · 2022-01-27T16:47:52Z

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1611UnitTests.cs

+    /// <summary>
+    /// Foo
+    /// </summary>
+    /// <param name=""param1"">The param1.</param>


📝 The content should not be added here, except in limited cases where the content is dictated by a specific design pattern.

Suggested change

/// <param name=""param1"">The param1.</param>

/// <param name=""param1""></param>

sharwell · 2022-01-27T16:48:13Z

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1611UnitTests.cs

+    /// Foo
+    /// </summary>
+    /// <param name=""param1"">Param 1</param>
+    /// <param name=""param2"">The param2.</param>


Suggested change

/// <param name=""param2"">The param2.</param>

/// <param name=""param2""></param>

sharwell · 2022-01-27T16:48:29Z

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1611UnitTests.cs

+    /// Foo
+    /// </summary>
+    /// <typeparam name=""TInternalRow"">The type of the internal row.</typeparam>
+    /// <param name=""param1"">The param1.</param>


Suggested change

/// <param name=""param1"">The param1.</param>

/// <param name=""param1""></param>

sharwell · 2022-01-27T16:48:38Z

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1611UnitTests.cs

+    /// </summary>
+    /// <param name=""param1"">The param1.</param>
+    /// <param name=""param2"">The param2.</param>
+    /// <param name=""param3"">The param3.</param>


Suggested change

/// <param name=""param3"">The param3.</param>

/// <param name=""param3""></param>

sharwell · 2022-01-27T16:51:06Z

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1618UnitTests.cs

+    /// Foo
+    /// </summary>
+    /// <typeparam name=""Ta"">The type of the ta.</typeparam>
+    /// <typeparam name=""Tb"">The type of the tb.</typeparam>


Suggested change

/// <typeparam name=""Tb"">The type of the tb.</typeparam>

/// <typeparam name=""Tb""></typeparam>

sharwell · 2022-01-27T16:51:57Z

StyleCop.Analyzers/StyleCop.Analyzers/StyleCop.Analyzers.csproj

+    <ProjectReference 
+      Include="..\StyleCop.Analyzers.CodeGeneration\StyleCop.Analyzers.CodeGeneration.csproj" 
+      SetTargetFramework="TargetFramework=netstandard2.0" 
+      OutputItemType="Analyzer" 


💭 I'm guessing the change here was unintentional?

sharwell · 2022-01-27T16:56:50Z

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

-    /// <param name=""param1""></param>
-    /// <param name=""param2""></param>
+    /// <param name=""param1"">The param1.</param>
+    /// <param name=""param2"">If true, param2.</param>


📝 The standard form for a Boolean-value property is:

<see langword="true"/> if [text]; otherwise, <see langword="false"/>.

This could be generated using a placeholder:

<see langword="true"/> if <placeholder>condition</placeholder>; otherwise, <see langword="false"/>.

sharwell · 2022-01-27T16:58:25Z

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

+                    Diagnostic().WithLocation(9, 17),
+                    Diagnostic().WithLocation(13, 16),
+                    Diagnostic().WithLocation(18, 16),
+                    Diagnostic().WithLocation(23, 16),
+                    Diagnostic().WithLocation(28, 40),
+                    Diagnostic().WithLocation(33, 25),
+                    Diagnostic().WithLocation(38, 25),


💡 Use [|...|] syntax inside of testCode to mark the diagnostic locations

sharwell · 2022-01-27T17:00:11Z

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

+/// <summary>
+/// Test class.
+/// </summary>
+public class TestClass


📝 Most values added in this test need to be updated according to other comments given previously.

bjornhellander · 2024-06-29T13:40:44Z

I'm looking through the older pull requests in this repo. Is this something that you will continue working on, @jgefen?

jgefen and others added 3 commits January 27, 2022 16:14

Add code fixes for documentation diagnostics (#1)

6819217

* Add helpers * Add documenation fix SA1600 for most types * Add SA1611 codefix * Add SA1602 codefix * Add SA1618 codefix Co-authored-by: Alon Sheffer <alon.sheffer@intel.com> Co-authored-by: Jonatan Gefen <jonatan.gefen@intel.com>

Style fixes

7a061b7

Merge pull request #2 from jgefen/DEV/styleFixes

9d2d366

Style fixes

sharwell requested changes Jan 27, 2022

View reviewed changes

	/// <param name=""param1"">The param1.</param>
	/// <param name=""param1""></param>

	/// <param name=""param2"">The param2.</param>
	/// <param name=""param2""></param>

	/// <param name=""param3"">The param3.</param>
	/// <param name=""param3""></param>

	/// <typeparam name=""Tb"">The type of the tb.</typeparam>
	/// <typeparam name=""Tb""></typeparam>

Conversation

jgefen commented Jan 27, 2022

Uh oh!

codecov bot commented Jan 27, 2022

Codecov Report

Uh oh!

sharwell commented Jan 27, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bjornhellander commented Jun 29, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants