Add option to return correction as vscode snippet

Author: Kapil Borle

Rules/ProvideCommentHelp.cs

@@ -41,6 +41,9 @@ public class ProvideCommentHelp : ConfigurableRule
         [ConfigurableRuleProperty(defaultValue: true)]
         public bool BlockComment { get; protected set; }
 
+        [ConfigurableRuleProperty(defaultValue: false)]
+        public bool VSCodeSnippetCorrection { get; protected set; }
+
         public ProvideCommentHelp() : base()
         {
             // Enable the rule by default
@@ -148,7 +151,7 @@ private IEnumerable<CorrectionExtent> GetCorrection(FunctionDefinitionAst funcDe
                 funcDefnAst.Extent.StartLineNumber,
                 funcDefnAst.Extent.StartColumnNumber,
                 funcDefnAst.Extent.StartColumnNumber,
-                helpBuilder.GetCommentHelp(BlockComment) + Environment.NewLine,
+                helpBuilder.GetCommentHelp(BlockComment, VSCodeSnippetCorrection) + Environment.NewLine,
                 funcDefnAst.Extent.File);
         }
 
@@ -220,20 +223,21 @@ public void AddParameter(string paramName)
                 parameters.Add(new ParameterHelpNode(paramName, "Parameter description"));
             }
 
-            public string GetCommentHelp(bool blockComment)
+            public string GetCommentHelp(bool blockComment, bool snippet)
             {
                 var sb = new StringBuilder();
+                var helpContent = snippet ? this.ToSnippetString() : this.ToString();
                 if (blockComment)
                 {
                     sb.AppendLine("<#");
-                    sb.AppendLine(this.ToString());
+                    sb.AppendLine(helpContent);
                     sb.Append("#>");
                 }
                 else
                 {
                     var boundaryString = new String('#', 30);
                     sb.AppendLine(boundaryString);
-                    var lines = this.ToString().Split('\n').Select(l => l.Trim('\r'));
+                    var lines = helpContent.Split('\n').Select(l => l.Trim('\r'));
                     foreach (var line in lines)
                     {
                         sb.Append("#");
@@ -261,6 +265,21 @@ public override string ToString()
                 return sb.ToString();
             }
 
+            // todo remove code duplication
+            public string ToSnippetString() {
+                var sb = new StringBuilder();
+                int tabStop = 1;
+                sb.AppendLine(synopsis.ToString(tabStop++)).AppendLine();
+                sb.AppendLine(description.ToString(tabStop++)).AppendLine();
+                foreach (var parameter in parameters)
+                {
+                    sb.AppendLine(parameter.ToString(tabStop++)).AppendLine();
+                }
+
+                sb.AppendLine(example.ToString(tabStop++)).AppendLine();
+                sb.Append(notes.ToString(tabStop++));
+                return sb.ToString();
+            }
             private class CommentHelpNode
             {
                 public CommentHelpNode(string nodeName, string description)
@@ -283,6 +302,18 @@ public override string ToString()
 
                     return sb.ToString();
                 }
+
+                public virtual string ToString(int tabStop)
+                {
+                    var sb = new StringBuilder();
+                    sb.Append(".").AppendLine(Name.ToUpper());
+                    if (!String.IsNullOrWhiteSpace(Description))
+                    {
+                        sb.Append($"${{{tabStop}:{Description}}}");
+                    }
+
+                    return sb.ToString();
+                }
             }
 
             private class ParameterHelpNode : CommentHelpNode
@@ -306,6 +337,18 @@ public override string ToString()
 
                     return sb.ToString();
                 }
+
+                public override string ToString(int tabStop)
+                {
+                    var sb = new StringBuilder();
+                    sb.Append(".").Append(Name.ToUpper()).Append(" ").AppendLine(ParameterName);
+                    if (!String.IsNullOrWhiteSpace(Description))
+                    {
+                        sb.Append($"${{{tabStop}:{Description}}}");
+                    }
+
+                    return sb.ToString();
+                }
             }
         }
     }

Tests/Rules/ProvideCommentHelp.tests.ps1

@@ -10,6 +10,7 @@ $ruleSettings = @{
     Enable = $true
     ExportedOnly = $false
     BlockComment = $true
+    VSCodeSnippetCorrection = $false
 }
 
 $settings = @{
@@ -178,6 +179,41 @@ Export-ModuleMember -Function foo
             Test-Correction $def $expectedCorrection $settings
         }
 
+        It "should return a vscode snippet with line comment style" {
+            $def = @'
+function foo {
+    param($param1, $param2)
+}
+
+Export-ModuleMember -Function foo
+'@
+            $expectedCorrection = @'
+##############################
+#.SYNOPSIS
+#${1:Short description}
+#
+#.DESCRIPTION
+#${2:Long description}
+#
+#.PARAMETER param1
+#${3:Parameter description}
+#
+#.PARAMETER param2
+#${4:Parameter description}
+#
+#.EXAMPLE
+#${5:An example}
+#
+#.NOTES
+#${6:General notes}
+##############################
+
+'@
+            $ruleSettings.'BlockComment' = $false
+            $ruleSettings.'VSCodeSnippetCorrection' = $true
+            Test-Correction $def $expectedCorrection $settings
+        }
+
         if ($PSVersionTable.PSVersion -ge [Version]'5.0.0') {
             It "Does not count violation in DSC class" {
                 $dscViolations.Count | Should Be 0
@@ -190,4 +226,4 @@ Export-ModuleMember -Function foo
             $noViolations.Count | Should Be 0
         }
     }
-}
+}