Format and add inline doc to public fields

Author: Kapil Borle

Engine/Generic/ConfigurableScriptRule.cs

@@ -8,17 +8,33 @@ namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic
     // This is still an experimental class. Use at your own risk!
     public abstract class ConfigurableScriptRule : IScriptRule
     {
-        // Configurable rule properties should define a default value
-        // because if reading the configuration fails
-        // we use the property's default value
+        /// <summary>
+        /// Indicates if the rule is enabled or not.
+        ///
+        /// If the rule is enabled ScriptAnalyzer engine will run it
+        /// otherwise it will not.
+        ///
+        /// Configurable rule properties should define a default value
+        /// because if reading the configuration fails we use the
+        /// property's default value
+        /// </summary>
         [ConfigurableRuleProperty(defaultValue: false)]
         public bool Enable { get; protected set; }
 
+        /// <summary>
+        /// Initialize the configurable properties of a configurable rule.
+        /// </summary>
         protected ConfigurableScriptRule()
         {
             SetDefaultValues();
         }
 
+        /// <summary>
+        /// Sets the configurable properties of the rule.
+        ///
+        /// Properties having ConfigurableRuleProperty attribute are called configurable properties.
+        /// </summary>
+        /// <param name="paramValueMap">A dictionary that maps parameter name to it value. Must be non-null</param>
         public virtual void ConfigureRule(IDictionary<string, object> paramValueMap)
         {
             if (paramValueMap == null)
@@ -45,6 +61,50 @@ public virtual void ConfigureRule(IDictionary<string, object> paramValueMap)
             }
         }
 
+        /// <summary>
+        /// Analyzes the given abstract syntax tree (AST) and returns diagnostic records based on the analysis.
+        /// </summary>
+        /// <param name="ast">AST representing the file content</param>
+        /// <param name="fileName">Path of the file corresponding to the AST</param>
+        /// <returns>The results of the analysis</returns>
+        public abstract IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName);
+
+        /// <summary>
+        /// Retrieves the Common name of the rule.
+        /// </summary>
+        /// <returns>The name of the rule.</returns>
+        public abstract string GetCommonName();
+
+        /// <summary>
+        /// Retrieves the description of the rule.
+        /// </summary>
+        /// <returns>The description of the rule.</returns>
+        public abstract string GetDescription();
+
+        /// <summary>
+        /// Retrieves the name of the rule.
+        /// </summary>
+        /// <returns>The name of the rule.</returns>
+        public abstract string GetName();
+
+        /// <summary>
+        /// Retrieves severity of the rule.
+        /// </summary>
+        /// <returns>The severity of the rule.</returns>
+        public abstract RuleSeverity GetSeverity();
+
+        /// <summary>
+        /// Retrieves the source name of the rule.
+        /// </summary>
+        /// <returns>The source name of the rule.</returns>
+        public abstract string GetSourceName();
+
+        /// <summary>
+        /// Retrieves the source type of the rule.
+        /// </summary>
+        /// <returns>The source type of the rule.</returns>
+        public abstract SourceType GetSourceType();
+
         private void SetDefaultValues()
         {
             foreach (var property in GetConfigurableProperties())
@@ -82,21 +142,23 @@ private Object GetDefaultValue(PropertyInfo property)
 
             return ((ConfigurableRulePropertyAttribute)attr).DefaultValue;
         }
-
-        public abstract IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName);
-        public abstract string GetCommonName();
-        public abstract string GetDescription();
-        public abstract string GetName();
-        public abstract RuleSeverity GetSeverity();
-        public abstract string GetSourceName();
-        public abstract SourceType GetSourceType();
     }
 
+    /// <summary>
+    /// The attribute class to designate if a property is configurable or not.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
     public class ConfigurableRulePropertyAttribute : Attribute
     {
+        /// <summary>
+        /// Default value of the property that the attribute decorates.
+        /// </summary>
         public object DefaultValue { get; private set; }
 
+        /// <summary>
+        /// Initialize the attribute with the decorated property's default value.
+        /// </summary>
+        /// <param name="defaultValue"></param>
         public ConfigurableRulePropertyAttribute(object defaultValue)
         {
             if (defaultValue == null)

Rules/PlaceCloseBrace.cs

@@ -28,11 +28,16 @@ namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
 #endif
     public class PlaceCloseBrace : ConfigurableScriptRule
     {
+        /// <summary>
+        /// Indicates if there should or should not be an empty line before a close brace.
+        ///
+        /// Default value if false.
+        /// </summary>
         [ConfigurableRuleProperty(defaultValue:false)]
         public bool NoEmptyLineBefore { get; protected set; }
 
         /// <summary>
-        /// Analyzes the given ast to find the [violation]
+        /// Analyzes the given ast to find violations.
         /// </summary>
         /// <param name="ast">AST to be analyzed. This should be non-null</param>
         /// <param name="fileName">Name of file that corresponds to the input AST.</param>
@@ -102,6 +107,67 @@ public override IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string file
             return diagnosticRecords;
         }
 
+        /// <summary>
+        /// Retrieves the common name of this rule.
+        /// </summary>
+        public override string GetCommonName()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.PlaceCloseBraceCommonName);
+        }
+
+        /// <summary>
+        /// Retrieves the description of this rule.
+        /// </summary>
+        public override string GetDescription()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.PlaceCloseBraceDescription);
+        }
+
+        /// <summary>
+        /// Retrieves the name of this rule.
+        /// </summary>
+        public override string GetName()
+        {
+            return string.Format(
+                CultureInfo.CurrentCulture,
+                Strings.NameSpaceFormat,
+                GetSourceName(),
+                Strings.PlaceCloseBraceName);
+        }
+
+        /// <summary>
+        /// Retrieves the severity of the rule: error, warning or information.
+        /// </summary>
+        public override RuleSeverity GetSeverity()
+        {
+            return RuleSeverity.Information;
+        }
+
+        /// <summary>
+        /// Gets the severity of the returned diagnostic record: error, warning, or information.
+        /// </summary>
+        /// <returns></returns>
+        public DiagnosticSeverity GetDiagnosticSeverity()
+        {
+            return DiagnosticSeverity.Information;
+        }
+
+        /// <summary>
+        /// Retrieves the name of the module/assembly the rule is from.
+        /// </summary>
+        public override string GetSourceName()
+        {
+            return string.Format(CultureInfo.CurrentCulture, Strings.SourceName);
+        }
+
+        /// <summary>
+        /// Retrieves the type of the rule, Builtin, Managed or Module.
+        /// </summary>
+        public override SourceType GetSourceType()
+        {
+            return SourceType.Builtin;
+        }
+
         private DiagnosticRecord GetViolationForBraceShouldNotFollowEmptyLine(
             Token[] tokens,
             int closeBracePos,
@@ -258,75 +324,9 @@ private List<Token> GetTokens(Ast ast, List<Token> tokens, ref Dictionary<Ast, L
             return tokenSet;
         }
 
-        /// <summary>
-        /// Retrieves the error message of this rule
-        /// </summary>
-        private string GetError(string errorString)
+        private static string GetError(string errorString)
         {
             return string.Format(CultureInfo.CurrentCulture, errorString);
         }
-
-        /// <summary>
-        /// Retrieves the common name of this rule.
-        /// </summary>
-        public override string GetCommonName()
-        {
-            return string.Format(CultureInfo.CurrentCulture, Strings.PlaceCloseBraceCommonName);
-        }
-
-        /// <summary>
-        /// Retrieves the description of this rule.
-        /// </summary>
-        public override string GetDescription()
-        {
-            return string.Format(CultureInfo.CurrentCulture, Strings.PlaceCloseBraceDescription);
-        }
-
-        /// <summary>
-        /// Retrieves the name of this rule.
-        /// </summary>
-        public override string GetName()
-        {
-            return string.Format(
-                CultureInfo.CurrentCulture,
-                Strings.NameSpaceFormat,
-                GetSourceName(),
-                Strings.PlaceCloseBraceName);
-        }
-
-        /// <summary>
-        /// Retrieves the severity of the rule: error, warning or information.
-        /// </summary>
-        public override RuleSeverity GetSeverity()
-        {
-            return RuleSeverity.Information;
-        }
-
-        /// <summary>
-        /// Gets the severity of the returned diagnostic record: error, warning, or information.
-        /// </summary>
-        /// <returns></returns>
-        public DiagnosticSeverity GetDiagnosticSeverity()
-        {
-            return DiagnosticSeverity.Information;
-        }
-
-        /// <summary>
-        /// Retrieves the name of the module/assembly the rule is from.
-        /// </summary>
-        public override string GetSourceName()
-        {
-            return string.Format(CultureInfo.CurrentCulture, Strings.SourceName);
-        }
-
-        /// <summary>
-        /// Retrieves the type of the rule, Builtin, Managed or Module.
-        /// </summary>
-        public override SourceType GetSourceType()
-        {
-            return SourceType.Builtin;
-        }
-
-
     }
 }