Merge pull request #282 from PowerShell/master

Master to BugFixes - Suppression Documentation

Author: raghushantha

CHANGELOG.MD

@@ -1,4 +1,4 @@
-## Released v1.0.2 (June.25, 2015)
+## Released v1.0.2 (June.24, 2015)
 ###Features:
 - Perf improvements in the Engine to execute rules concurrently.
 

README.md

@@ -39,6 +39,87 @@ If you have previous version of PSScriptAnalyzer installed on your machine, you
 
 To confirm installation: run ```Get-ScriptAnalyzerRule``` in the PowerShell console to obtain the built-in rules
 
+Suppressing Rules
+=================
+
+You can suppress a rule by decorating a script/function or script/function parameter with .NET's [SuppressMessageAttribute](https://msdn.microsoft.com/en-us/library/system.diagnostics.codeanalysis.suppressmessageattribute.aspx).  `SuppressMessageAttribute`'s constructor takes two parameters: a category and a check ID. Set the `categoryID` parameter to the name of the rule you want to suppress (you may omit the `checkID` parameter):
+
+    function SuppressMe()
+    {
+        [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideCommentHelp")]
+        param()
+
+        Write-Verbose -Message "I'm making a difference!"
+        
+    }
+    
+All rule violations within the scope of the script/function/parameter you decorate will be suppressed.
+    
+To suppress a message on a specific parameter, set the `SuppressMessageAttribute`'s `CheckId` parameter to the name of the parameter:
+
+    function SuppressTwoVariables()
+    {
+        [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideDefaultParameterValue", "b")]
+        [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideDefaultParameterValue", "a")]
+        param([string]$a, [int]$b)
+        {
+        }
+    }
+
+Use the `SuppressMessageAttribute`'s `Scope` property to limit rule suppression to functions or classes within the attribute's scope. Use the value `Function` to suppress violations on all functions within the attribute's scope. Use the value `Class` to suppress violoations on all classes within the attribute's scope:
+
+
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSProvideCommentHelp", "", Scope="Function")]
+    param(
+    )
+    
+    function InternalFunction
+    {
+        param()
+        
+        Write-Verbose -Message "I am invincible!"
+    }
+    
+The above example demonstrates how to suppress rule violations for internal functions using the `SuppressMessageAttribute`'s `Scope` property.
+
+You can further restrict suppression based on a function/parameter/class/variable/object's name by setting the `SuppressMessageAttribute's` `Target` property to a regular expression. Any function/parameter/class/variable/object whose name matches the regular expression is skipped.
+
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPositionalParameters", Scope="Function", Target="PositionalParametersAllowed")]
+    Param(
+    )
+     
+    function PositionalParametersAllowed()
+    {
+        Param([string]$Parameter1)
+        {
+            Write-Verbose $Parameter1
+        }
+    
+    }
+    
+    function PositionalParametersNotAllowed()
+    {
+        param([string]$Parameter1)
+        {
+            Write-Verbose $Parameter1
+        }
+    }
+    
+    # The script analyzer will skip this violation
+    PositionalParametersAllowed 'value1'
+    
+    # The script analyzer will report this violation
+    PositionalParametersNotAllowed 'value1
+    
+To match all functions/variables/parameters/objects, use `*` as the value of the Target parameter:
+
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPositionalParameters", Scope="Function", Target="*")]
+    Param(
+    )
+
+
+
+
 Building the Code
 =================