Add doc comments to extension methods.

Author: Hosch250

RetailCoder.VBE/Common/DeclarationExtensions.cs

@@ -21,6 +21,12 @@ public static BitmapImage BitmapImage(this Declaration declaration)
             return Cache[declaration];
         }
 
+        /// <summary>
+        /// Returns the Selection of a VariableStmtContext.
+        /// </summary>
+        /// <exception cref="ArgumentException">Throws when target's DeclarationType is not Variable.</exception>
+        /// <param name="target"></param>
+        /// <returns></returns>
         public static Selection GetVariableStmtContextSelection(this Declaration target)
         {
             if (target.DeclarationType != DeclarationType.Variable)
@@ -34,6 +40,12 @@ public static Selection GetVariableStmtContextSelection(this Declaration target)
                     statement.Stop.Line, statement.Stop.Column);
         }
 
+        /// <summary>
+        /// Returns a VariableStmtContext.
+        /// </summary>
+        /// <exception cref="ArgumentException">Throws when target's DeclarationType is not Variable.</exception>
+        /// <param name="target"></param>
+        /// <returns></returns>
         public static VBAParser.VariableStmtContext GetVariableStmtContext(this Declaration target)
         {
             if (target.DeclarationType != DeclarationType.Variable)
@@ -50,6 +62,12 @@ public static VBAParser.VariableStmtContext GetVariableStmtContext(this Declarat
             return statement;
         }
 
+        /// <summary>
+        /// Returns whether a variable declaration statement contains multiple declarations in a single statement.
+        /// </summary>
+        /// <exception cref="ArgumentException">Throws when target's DeclarationType is not Variable.</exception>
+        /// <param name="target"></param>
+        /// <returns></returns>
         public static bool HasMultipleDeclarationsInStatement(this Declaration target)
         {
             if (target.DeclarationType != DeclarationType.Variable)
@@ -312,7 +330,15 @@ public static Declaration FindInterfaceMember(this IEnumerable<Declaration> decl
                 : matches.First();
         }
 
-        public static Declaration FindSelection(this IEnumerable<Declaration> declarations, QualifiedSelection selection, DeclarationType[] validDeclarationTypes)
+        /// <summary>
+        /// Returns the declaration contained in a qualified selection.
+        /// To get the selection of a variable or field, use FindVariable(QualifiedSelection)
+        /// </summary>
+        /// <param name="declarations"></param>
+        /// <param name="selection"></param>
+        /// <param name="validDeclarationTypes"></param>
+        /// <returns></returns>
+        public static Declaration FindTarget(this IEnumerable<Declaration> declarations, QualifiedSelection selection, DeclarationType[] validDeclarationTypes)
         {
             var items = declarations.ToList();
 
@@ -375,6 +401,12 @@ public static Declaration FindSelection(this IEnumerable<Declaration> declaratio
             return target;
         }
 
+        /// <summary>
+        /// Returns the variable which contains the passed-in QualifiedSelection.  Returns null if the selection is not on a variable.
+        /// </summary>
+        /// <param name="declarations"></param>
+        /// <param name="selection"></param>
+        /// <returns></returns>
         public static Declaration FindVariable(this IEnumerable<Declaration> declarations, QualifiedSelection selection)
         {
             var items = declarations.Where(d => !d.IsBuiltIn && d.DeclarationType == DeclarationType.Variable).ToList();

RetailCoder.VBE/Navigation/RegexSearchReplace/RegexSearchReplace.cs

@@ -132,7 +132,7 @@ private List<RegexSearchResult> SearchCurrentBlock(string searchPattern)
 
             var wrapper = _codePaneFactory.Create(_vbe.ActiveCodePane);
             var qualifiedSelection = new QualifiedSelection(new QualifiedModuleName(wrapper.CodeModule.Parent), wrapper.Selection);
-            dynamic block = parseResult.AllDeclarations.FindSelection(qualifiedSelection, declarationTypes).Context.Parent;
+            dynamic block = parseResult.AllDeclarations.FindTarget(qualifiedSelection, declarationTypes).Context.Parent;
             var selection = new Selection(block.Start.Line, block.Start.Column, block.Stop.Line, block.Stop.Column);
             return results.Where(r => selection.Contains(r.Selection)).ToList();
         }

RetailCoder.VBE/Refactorings/IntroduceParameter/IntroduceParameterRefactoring.cs

@@ -81,7 +81,7 @@ private void PromoteVariable(Declaration target)
 
         private bool PromptIfMethodImplementsInterface(Declaration targetVariable)
         {
-            var functionDeclaration = _declarations.FindSelection(targetVariable.QualifiedSelection, ValidDeclarationTypes);
+            var functionDeclaration = _declarations.FindTarget(targetVariable.QualifiedSelection, ValidDeclarationTypes);
             var interfaceImplementation = GetInterfaceImplementation(functionDeclaration);
 
             if (interfaceImplementation == null)
@@ -100,7 +100,7 @@ private bool PromptIfMethodImplementsInterface(Declaration targetVariable)
 
         private void UpdateSignature(Declaration targetVariable)
         {
-            var functionDeclaration = _declarations.FindSelection(targetVariable.QualifiedSelection, ValidDeclarationTypes);
+            var functionDeclaration = _declarations.FindTarget(targetVariable.QualifiedSelection, ValidDeclarationTypes);
 
             var proc = (dynamic)functionDeclaration.Context;
             var paramList = (VBAParser.ArgListContext)proc.argList();

RetailCoder.VBE/Refactorings/RemoveParameters/RemoveParametersModel.cs

@@ -36,7 +36,7 @@ public RemoveParametersModel(RubberduckParserState parseResult, QualifiedSelecti
 
         private void AcquireTarget(QualifiedSelection selection)
         {
-            TargetDeclaration = Declarations.FindSelection(selection, ValidDeclarationTypes);
+            TargetDeclaration = Declarations.FindTarget(selection, ValidDeclarationTypes);
             TargetDeclaration = PromptIfTargetImplementsInterface();
             TargetDeclaration = GetGetter();
         }

RetailCoder.VBE/Refactorings/RemoveParameters/RemoveParametersRefactoring.cs

@@ -62,7 +62,7 @@ public void Refactor(Declaration target)
         public void QuickFix(RubberduckParserState parseResult, QualifiedSelection selection)
         {
             _model = new RemoveParametersModel(parseResult, selection, new MessageBox());
-            var target = _model.Declarations.FindSelection(selection, new[] { DeclarationType.Parameter });
+            var target = _model.Declarations.FindTarget(selection, new[] { DeclarationType.Parameter });
 
             // ReSharper disable once PossibleUnintendedReferenceComparison
             _model.Parameters.Find(param => param.Declaration == target).IsRemoved = true;

RetailCoder.VBE/Refactorings/ReorderParameters/ReorderParametersModel.cs

@@ -37,7 +37,7 @@ public ReorderParametersModel(RubberduckParserState parseResult, QualifiedSelect
 
         private void AcquireTarget(QualifiedSelection selection)
         {
-            TargetDeclaration = Declarations.FindSelection(selection, ValidDeclarationTypes);
+            TargetDeclaration = Declarations.FindTarget(selection, ValidDeclarationTypes);
             TargetDeclaration = PromptIfTargetImplementsInterface();
             TargetDeclaration = GetGetter();
         }