Add option for comment help placement

Author: Kapil Borle

Rules/ProvideCommentHelp.cs

@@ -33,9 +33,6 @@ namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
 #endif
     public class ProvideCommentHelp : ConfigurableRule
     {
-
-        // todo add option for comment type
-        // todo add option for help placement (beforeFuntion, BodyStart, BodyEnd:)
         [ConfigurableRuleProperty(defaultValue: true)]
         public bool ExportedOnly { get; protected set; }
 
@@ -45,6 +42,10 @@ public class ProvideCommentHelp : ConfigurableRule
         [ConfigurableRuleProperty(defaultValue: false)]
         public bool VSCodeSnippetCorrection { get; protected set; }
 
+        // possible options: before, begin, end
+        [ConfigurableRuleProperty(defaultValue: "before")]
+        public string Placement { get; protected set; }
+
         public ProvideCommentHelp() : base()
         {
             // Enable the rule by default
@@ -146,16 +147,66 @@ private IEnumerable<CorrectionExtent> GetCorrection(FunctionDefinitionAst funcDe
                 helpBuilder.AddParameter(paramAst.Name.VariablePath.UserPath);
             }
 
-            var correctionExtents = new List<CorrectionExtent>();
+            int startLine, endLine, startColumn, endColumn;
+            GetCorrectionPosition(funcDefnAst, out startLine, out endLine, out startColumn, out endColumn);
             yield return new CorrectionExtent(
-                funcDefnAst.Extent.StartLineNumber,
-                funcDefnAst.Extent.StartLineNumber,
-                funcDefnAst.Extent.StartColumnNumber,
-                funcDefnAst.Extent.StartColumnNumber,
-                helpBuilder.GetCommentHelp(BlockComment, VSCodeSnippetCorrection) + Environment.NewLine,
+                startLine,
+                endLine,
+                startColumn,
+                endColumn,
+                ProcessCorrectionForPlacement(
+                    helpBuilder.GetCommentHelp(
+                        BlockComment,
+                        VSCodeSnippetCorrection)),
                 funcDefnAst.Extent.File);
         }
 
+        private string ProcessCorrectionForPlacement(string correction)
+        {
+            switch (Placement.ToLower())
+            {
+                case "begin":
+                    return "{" + Environment.NewLine + correction + Environment.NewLine;
+                case "end":
+                    return Environment.NewLine + correction + Environment.NewLine;
+                default:
+                    return correction + Environment.NewLine;
+            }
+        }
+
+        private void GetCorrectionPosition(
+            FunctionDefinitionAst funcDefnAst,
+            out int startLine,
+            out int endLine,
+            out int startColumn,
+            out int endColumn)
+        {
+            // the better thing to do is get the line/column from corresponding tokens
+            switch (Placement.ToLower())
+            {
+                case "begin":
+                    startLine = funcDefnAst.Body.Extent.StartLineNumber;
+                    endLine = startLine;
+                    startColumn = funcDefnAst.Body.Extent.StartColumnNumber;
+                    endColumn = startColumn + 1;
+                    break;
+
+                case "end":
+                    startLine = funcDefnAst.Body.Extent.EndLineNumber;
+                    endLine = startLine;
+                    startColumn = funcDefnAst.Body.Extent.EndColumnNumber - 1;
+                    endColumn = startColumn;
+                    break;
+
+                default: // before
+                    startLine = funcDefnAst.Extent.StartLineNumber;
+                    endLine = startLine;
+                    startColumn = funcDefnAst.Extent.StartColumnNumber;
+                    endColumn = startColumn;
+                    break;
+            }
+        }
+
         private class ViolationFinder : AstVisitor
         {
             private HashSet<string> functionWhitelist;

Tests/Rules/ProvideCommentHelp.tests.ps1

@@ -10,6 +10,7 @@ $ruleSettings = @{
     Enable = $true
     ExportedOnly = $false
     BlockComment = $true
+    Placement = "before"
     VSCodeSnippetCorrection = $false
 }
 
@@ -214,6 +215,78 @@ Export-ModuleMember -Function foo
             Test-Correction $def $expectedCorrection $settings
         }
 
+        It "should return a help snippet correction with 2 parameters at the begining of function body" {
+            $def = @'
+function foo {
+    param($param1, $param2)
+}
+'@
+            $expectedCorrection = @'
+{
+<#
+.SYNOPSIS
+Short description
+
+.DESCRIPTION
+Long description
+
+.PARAMETER param1
+Parameter description
+
+.PARAMETER param2
+Parameter description
+
+.EXAMPLE
+An example
+
+.NOTES
+General notes
+#>
+
+'@
+            $ruleSettings.'ExportedOnly' = $false
+            $ruleSettings.'BlockComment' = $true
+            $ruleSettings.'VSCodeSnippetCorrection' = $false
+            $ruleSettings.'Placement' = 'begin'
+            Test-Correction $def $expectedCorrection $settings
+        }
+
+        It "should return a help snippet correction with 2 parameters at the end of function body" {
+            $def = @'
+function foo {
+    param($param1, $param2)
+}
+'@
+            $expectedCorrection = @'
+
+<#
+.SYNOPSIS
+Short description
+
+.DESCRIPTION
+Long description
+
+.PARAMETER param1
+Parameter description
+
+.PARAMETER param2
+Parameter description
+
+.EXAMPLE
+An example
+
+.NOTES
+General notes
+#>
+
+'@
+            $ruleSettings.'ExportedOnly' = $false
+            $ruleSettings.'BlockComment' = $true
+            $ruleSettings.'VSCodeSnippetCorrection' = $false
+            $ruleSettings.'Placement' = 'end'
+            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