Update XMLDoc content

BZngr · BZngr · commit b771e1f21627 · 2020-09-21T10:20:13.000-07:00
diff --git a/Rubberduck.Refactorings/CreateUDTMember/CreateUDTMemberRefactoringAction.cs b/Rubberduck.Refactorings/CreateUDTMember/CreateUDTMemberRefactoringAction.cs
@@ -8,6 +8,11 @@
 using System.Linq;
 namespace Rubberduck.Refactorings.CreateUDTMember
 {
+    /// <summary>
+    /// CreateUDTMemberRefactoringAction adds a UserDefinedTypeMember declaration (based on a
+    /// prototype declaation) to a UserDefinedType declaration.  The indentation of the first 
+    /// existing member is used by the inserted members.  The caller is responsible for identifier validation and name collision anaysis.
+    /// </summary>
     public class CreateUDTMemberRefactoringAction : CodeOnlyRefactoringActionBase<CreateUDTMemberModel>
     {
         private readonly IDeclarationFinderProvider _declarationFinderProvider;
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldCollectionsProvider.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldCollectionsProvider.cs
@@ -14,15 +14,10 @@ public interface IEncapsulateFieldCollectionsProvider
     }
 
     /// <summary>
-    /// EncapsulateFieldCollectionsProvider generates collections IEncapsulateFieldCandidate
+    /// EncapsulateFieldCollectionsProvider generates collections of IEncapsulateFieldCandidate
     /// instances, IEncapsulateFieldAsUDTMemberCandidate instances, and IObjectStateUDT instances.
-    /// It provides these collections to the various objects of the EncapsulateFieldRefactoring 
-    /// so that they all operate in the same object sets.
+    /// It provides these collection instances to the various objects of the EncapsulateFieldRefactoring.
     /// </summary>
-    /// <remarks>
-    /// The EncapsulateFieldCollectionsProvider is the source of these collections for the various objects of 
-    /// the EncapsulateFieldRefactoring so that they all operate in the same set of object instances.
-    /// </remarks>
     public class EncapsulateFieldCollectionsProvider : IEncapsulateFieldCollectionsProvider
     {
         private readonly IDeclarationFinderProvider _declarationFinderProvider;
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldCollectionsProviderFactory.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldCollectionsProviderFactory.cs
@@ -1,11 +1,6 @@
 ﻿using Rubberduck.Parsing.VBA;
 using Rubberduck.Refactorings.EncapsulateField;
 using Rubberduck.VBEditor;
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace Rubberduck.Refactorings
 {
@@ -39,5 +34,4 @@ public IEncapsulateFieldCollectionsProvider Create(QualifiedModuleName qualified
                 qualifiedModuleName);
         }
     }
-
 }
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldInsertNewCode/EncapsulateFieldCodeBuilder.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldInsertNewCode/EncapsulateFieldCodeBuilder.cs
@@ -14,6 +14,10 @@ public interface IEncapsulateFieldCodeBuilder
         string BuildFieldDeclaration(Declaration target, string identifier);
     }
 
+    /// <summary>
+    /// EncapsulateFieldCodeBuilder wraps an ICodeBuilder instance to extend it for the 
+    /// specific needs of an EncapsulateField refactoring action.
+    /// </summary>
     public class EncapsulateFieldCodeBuilder : IEncapsulateFieldCodeBuilder
     {
         private const string FourSpaces = "    ";
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldInsertNewCode/EncapsulateFieldInsertNewCodeRefactoringAction.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldInsertNewCode/EncapsulateFieldInsertNewCodeRefactoringAction.cs
@@ -11,6 +11,10 @@
 
 namespace Rubberduck.Refactorings.EncapsulateFieldInsertNewCode
 {
+    /// <summary>
+    /// EncapsulateFieldInsertNewCodeRefactoringAction is a refactoring action dedicated to
+    /// the insertion of new code content generated by EncapsulateField refactoring actions
+    /// </summary>
     public class EncapsulateFieldInsertNewCodeRefactoringAction : CodeOnlyRefactoringActionBase<EncapsulateFieldInsertNewCodeModel>
     {
         private readonly IDeclarationFinderProvider _declarationFinderProvider;
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldInsertNewCode/NewContentAggregator.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldInsertNewCode/NewContentAggregator.cs
@@ -13,13 +13,35 @@ public enum NewContentType
 
     public interface INewContentAggregator
     {
+        /// <summary>
+        /// Allows gouping content blocks by <c>NewContentType</c>.
+        /// </summary>
         void AddNewContent(NewContentType contentType, string block);
+        /// <summary>
+        /// Allows gouping content blocks by an adhoc identifier.
+        /// </summary>
         void AddNewContent(string contentIdentifier, string block);
+        /// <summary>
+        /// Retrieves a block of content aggregated by <c>NewContentType</c>.
+        /// </summary>
+        /// <param name="newContentTypes"><c>NewContentType</c> blocks to aggregate</param>
         string RetrieveBlock(params NewContentType[] newContentTypes);
+        /// <summary>
+        /// Retrieves a block of content aggregated by a user-determined identifier.
+        /// </summary>
+        /// <param name="contentIdentifiers"><c>NewContentType</c> blocks to aggregate</param>
         string RetrieveBlock(params string[] contentIdentifiers);
+        /// <summary>
+        /// Sets default number of NewLines between blocks of code after
+        /// all retrieving block(s) of code.  The default value is 2.
+        /// </summary>
         int NewLineLimit { set; get; }
     }
 
+    /// <summary>
+    /// NewContentAggregator provides a repository for caching generated code blocks
+    /// and retrieving them as an aggregated single block of code organized by <c>NewContentType</c>.
+    /// </summary>
     public class NewContentAggregator : INewContentAggregator
     {
         private readonly static string _doubleSpace = $"{Environment.NewLine}{Environment.NewLine}";
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldModel.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldModel.cs
@@ -6,6 +6,11 @@
 
 namespace Rubberduck.Refactorings.EncapsulateField
 {
+    /// <summary>
+    /// The EncapsulateFieldModel provides a facade to the EncapsulateFieldRefactoring
+    /// by aggregating and simplifying access to the EncapsulateFieldUseBackingFieldModel 
+    /// and the EncapsulateFieldUseBackingUDTMemberModel.
+    /// </summary>
     public class EncapsulateFieldModel : IRefactoringModel
     {
         public EncapsulateFieldModel(EncapsulateFieldUseBackingFieldModel backingFieldModel,
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldRefactoringActionsProvider.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldRefactoringActionsProvider.cs
@@ -15,6 +15,10 @@ public interface IEncapsulateFieldRefactoringActionsProvider
         ICodeOnlyRefactoringAction<EncapsulateFieldInsertNewCodeModel> EncapsulateFieldInsertNewCode { get; }
     }
 
+    /// <summary>
+    /// EncapsulateFieldRefactoringActionsProvider reduces the number of EncapsulateField refactoring action 
+    /// constructor parameters providing refactoring actions common to the aggregated EncapsulateFieldRefactoringActions
+    /// </summary>
     public class EncapsulateFieldRefactoringActionsProvider : IEncapsulateFieldRefactoringActionsProvider
     {
         private readonly ReplaceReferencesRefactoringAction _replaceReferences;
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldUseBackingField/EncapsulateFieldUseBackingFieldModelFactory.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldUseBackingField/EncapsulateFieldUseBackingFieldModelFactory.cs
@@ -1,5 +1,4 @@
-﻿using Rubberduck.Parsing.Symbols;
-using Rubberduck.Refactorings.EncapsulateField;
+﻿using Rubberduck.Refactorings.EncapsulateField;
 using Rubberduck.Refactorings.EncapsulateFieldUseBackingField;
 using System.Collections.Generic;
 using System.Linq;
@@ -11,13 +10,12 @@ public interface IEncapsulateFieldUseBackingFieldModelFactory
         /// <summary>
         /// Creates an <c>EncapsulateFieldUseBackingFieldModel</c> used by the <c>EncapsulateFieldUseBackingFieldRefactoringAction</c>.
         /// </summary>
-        /// <param name="clientTarget">Optional: <c>UserDefinedType</c> Field to include the Encapsulated Field(s)</param>
         EncapsulateFieldUseBackingFieldModel Create(IEnumerable<FieldEncapsulationModel> requests);
 
         /// <summary>
         /// Creates an <c>EncapsulateFieldUseBackingFieldModel</c> based upon collection of
         /// <c>IEncapsulateFieldCandidate</c> instances created by <c>EncapsulateFieldCandidateCollectionFactory</c>.  
-        /// This function is intended for exclusive use by <c>EncapsulateFieldModelFactory</c>
+        /// This function is intended for exclusive use by the <c>EncapsulateFieldModelFactory</c>
         /// </summary>
         EncapsulateFieldUseBackingFieldModel Create(IEncapsulateFieldCollectionsProvider collectionsProvider, IEnumerable<FieldEncapsulationModel> requests);
     }
diff --git a/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldUseBackingUDTMember/EncapsulateFieldUseBackingUDTMemberModelFactory.cs b/Rubberduck.Refactorings/EncapsulateField/EncapsulateFieldUseBackingUDTMember/EncapsulateFieldUseBackingUDTMemberModelFactory.cs
@@ -12,13 +12,13 @@ public interface IEncapsulateFieldUseBackingUDTMemberModelFactory
         /// <summary>
         /// Creates an <c>EncapsulateFieldUseBackingUDTMemberModel</c> used by the <c>EncapsulateFieldUseBackingUDTMemberRefactoringAction</c>.
         /// </summary>
-        /// <param name="clientTarget">Optional: <c>UserDefinedType</c> Field to include the Encapsulated Field(s)</param>
+        /// <param name="userDefinedTypeTarget">Optional: <c>UserDefinedType</c> Field to host the Encapsulated Field(s)</param>
         EncapsulateFieldUseBackingUDTMemberModel Create(IEnumerable<FieldEncapsulationModel> requests, Declaration userDefinedTypeTarget = null);
 
         /// <summary>
         /// Creates an <c>EncapsulateFieldUseBackingUDTMemberModel</c> based upon collection of
         /// <c>IEncapsulateFieldCandidate</c> instances created by <c>EncapsulateFieldCandidateCollectionFactory</c>.  
-        /// This function is intended for exclusive use by <c>EncapsulateFieldModelFactory</c>
+        /// This function is intended for exclusive use by the <c>EncapsulateFieldModelFactory</c>
         /// </summary>
         EncapsulateFieldUseBackingUDTMemberModel Create(IEncapsulateFieldCollectionsProvider collectionsProvider, IEnumerable<FieldEncapsulationModel> requests, Declaration userDefinedTypeTarget = null);
     }
diff --git a/Rubberduck.Refactorings/EncapsulateField/FieldCandidates/EncapsulateFieldAsUDTMemberCandidate.cs b/Rubberduck.Refactorings/EncapsulateField/FieldCandidates/EncapsulateFieldAsUDTMemberCandidate.cs
@@ -13,7 +13,7 @@ public interface IEncapsulateFieldAsUDTMemberCandidate : IEncapsulateFieldCandid
 
     /// <summary>
     /// EncapsulateFieldAsUDTMemberCandidate wraps an IEncapusulateFieldCandidate instance
-    /// for the purposes of declaring its backing field as a UserDefinedTypeMember
+    /// for the purposes of declaring it as a new UserDefinedTypeMember
     /// within an existing or new UserDefinedType
     /// </summary>
     public class EncapsulateFieldAsUDTMemberCandidate : IEncapsulateFieldAsUDTMemberCandidate
diff --git a/Rubberduck.Refactorings/EncapsulateField/FieldCandidates/UserDefinedTypeCandidate.cs b/Rubberduck.Refactorings/EncapsulateField/FieldCandidates/UserDefinedTypeCandidate.cs
@@ -72,14 +72,14 @@ public override bool EncapsulateFlag
         {
             set
             {
+                base.EncapsulateFlag = value;
                 if (TypeDeclarationIsPrivate)
                 {
                     foreach (var member in Members)
                     {
                         member.EncapsulateFlag = value;
                     }
                 }
-                base.EncapsulateFlag = value;
             }
             get => base.EncapsulateFlag;
         }
diff --git a/Rubberduck.Refactorings/EncapsulateField/FieldEncapsulationModel.cs b/Rubberduck.Refactorings/EncapsulateField/FieldEncapsulationModel.cs
@@ -3,13 +3,13 @@
 namespace Rubberduck.Refactorings.EncapsulateField
 {
     /// <summary>
-    /// <c>FieldEncapsulationModel</c> contains attributes necessary for the <c>EncapsulateFieldUseBackingFieldRefactoringAction</c>
+    /// <c>FieldEncapsulationModel</c> consolidates attributes necessary for the <c>EncapsulateFieldUseBackingFieldRefactoringAction</c>
     /// and the <c>EncapsulateFieldUseBackingUDTMemberRefactoringAction</c>.
     /// </summary>
     /// <remarks>
-    /// There is no validation or conflict checking performed for non-UserDefinedTypes.
+    /// There is no identifier validation or conflict checking performed.
     /// If the target is a UserDefinedType Field and the UserDefinedType is Private,
-    /// then the propertyIdentifier parameter is ignored and PropertyIdentifiers for each UserDefinedTypeMember
+    /// then the <c>propertyIdentifier</c> parameter is ignored and PropertyIdentifiers for each UserDefinedTypeMember
     /// are generated by the refactoring action.
     /// </remarks>
     public class FieldEncapsulationModel
diff --git a/Rubberduck.Refactorings/EncapsulateField/ObjectStateUDT/ObjectStateUDT.cs b/Rubberduck.Refactorings/EncapsulateField/ObjectStateUDT/ObjectStateUDT.cs
@@ -4,8 +4,6 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using Rubberduck.Resources;
-using Rubberduck.Parsing.Grammar;
 
 namespace Rubberduck.Refactorings.EncapsulateField
 {
@@ -22,11 +20,11 @@ public interface IObjectStateUDT : IEncapsulateFieldRefactoringElement
 
     /// <summary>
     /// ObjectStateUDT is a Private UserDefinedType whose UserDefinedTypeMembers represent
-    /// object state in lieu of (or in addition to) a set of Private fields.
+    /// a consolidated grouping of object state in lieu of (or in addition to) a set of Private fields.
     /// </summary>
     /// <remarks>
     /// Within the EncapsulateField refactoring, the ObjectStateUDT can be an existing
-    /// UserDefinedType or an identifier that will be used to generate a new UserDefinedType
+    /// UserDefinedType or a new UserDefinedType generated by the refactoring.
     /// </remarks>
     public class ObjectStateUDT : IObjectStateUDT
     {
diff --git a/Rubberduck.Refactorings/EncapsulateField/PropertyAttributeSetsGenerator.cs b/Rubberduck.Refactorings/EncapsulateField/PropertyAttributeSetsGenerator.cs
@@ -24,6 +24,16 @@ public interface IPropertyAttributeSetsGenerator
         IReadOnlyCollection<PropertyAttributeSet> GeneratePropertyAttributeSets(IEncapsulateFieldCandidate candidate);
     }
 
+    /// <summary>
+    /// PropertyAttributeSetsGenerator operates on an <c>IEncapsulateFieldCandidate</c> instance to
+    /// generate a collection of <c>PropertyAttributeSet</c>s used by the EncapsulateField refactoring
+    /// actions to generate Property Let/Set/Get code blocks.
+    /// </summary>
+    /// <remarks>
+    /// Typically there is only a single <c>PropertyAttributeSet</c> in the collection.
+    /// In the case of a Private UserDefinedType, there will be a <c>PropertyAttributeSet</c>
+    /// for each UserDefinedTypeMember.
+    /// </remarks>
     public class PropertyAttributeSetsGenerator : IPropertyAttributeSetsGenerator
     {
         private Func<IEncapsulateFieldCandidate, string, string> _backingFieldQualifierFunc;

Original file line number	Diff line number	Diff line change
`@@ -8,6 +8,11 @@`
`8`	`8`	`using System.Linq;`
`9`	`9`	`namespace Rubberduck.Refactorings.CreateUDTMember`
`10`	`10`	`{`
	`11`	`+ /// <summary>`
	`12`	`+ /// CreateUDTMemberRefactoringAction adds a UserDefinedTypeMember declaration (based on a`
	`13`	`+ /// prototype declaation) to a UserDefinedType declaration. The indentation of the first`
	`14`	`+ /// existing member is used by the inserted members. The caller is responsible for identifier validation and name collision anaysis.`
	`15`	`+ /// </summary>`
`11`	`16`	`public class CreateUDTMemberRefactoringAction : CodeOnlyRefactoringActionBase<CreateUDTMemberModel>`
`12`	`17`	`{`
`13`	`18`	`private readonly IDeclarationFinderProvider _declarationFinderProvider;`
Original file line number	Diff line number	Diff line change
`@@ -1,11 +1,6 @@`
`1`	`1`	`using Rubberduck.Parsing.VBA;`
`2`	`2`	`using Rubberduck.Refactorings.EncapsulateField;`
`3`	`3`	`using Rubberduck.VBEditor;`
`4`		`-using System;`
`5`		`-using System.Collections.Generic;`
`6`		`-using System.Linq;`
`7`		`-using System.Text;`
`8`		`-using System.Threading.Tasks;`
`9`	`4`
`10`	`5`	`namespace Rubberduck.Refactorings`
`11`	`6`	`{`
`@@ -39,5 +34,4 @@ public IEncapsulateFieldCollectionsProvider Create(QualifiedModuleName qualified`
`39`	`34`	`qualifiedModuleName);`
`40`	`35`	`}`
`41`	`36`	`}`
`42`		`-`
`43`	`37`	`}`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,10 @@ public interface IEncapsulateFieldCodeBuilder`
`14`	`14`	`string BuildFieldDeclaration(Declaration target, string identifier);`
`15`	`15`	`}`
`16`	`16`
	`17`	`+ /// <summary>`
	`18`	`+ /// EncapsulateFieldCodeBuilder wraps an ICodeBuilder instance to extend it for the`
	`19`	`+ /// specific needs of an EncapsulateField refactoring action.`
	`20`	`+ /// </summary>`
`17`	`21`	`public class EncapsulateFieldCodeBuilder : IEncapsulateFieldCodeBuilder`
`18`	`22`	`{`
`19`	`23`	`private const string FourSpaces = " ";`
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,10 @@`
`11`	`11`
`12`	`12`	`namespace Rubberduck.Refactorings.EncapsulateFieldInsertNewCode`
`13`	`13`	`{`
	`14`	`+ /// <summary>`
	`15`	`+ /// EncapsulateFieldInsertNewCodeRefactoringAction is a refactoring action dedicated to`
	`16`	`+ /// the insertion of new code content generated by EncapsulateField refactoring actions`
	`17`	`+ /// </summary>`
`14`	`18`	`public class EncapsulateFieldInsertNewCodeRefactoringAction : CodeOnlyRefactoringActionBase<EncapsulateFieldInsertNewCodeModel>`
`15`	`19`	`{`
`16`	`20`	`private readonly IDeclarationFinderProvider _declarationFinderProvider;`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,11 @@`
`6`	`6`
`7`	`7`	`namespace Rubberduck.Refactorings.EncapsulateField`
`8`	`8`	`{`
	`9`	`+ /// <summary>`
	`10`	`+ /// The EncapsulateFieldModel provides a facade to the EncapsulateFieldRefactoring`
	`11`	`+ /// by aggregating and simplifying access to the EncapsulateFieldUseBackingFieldModel`
	`12`	`+ /// and the EncapsulateFieldUseBackingUDTMemberModel.`
	`13`	`+ /// </summary>`
`9`	`14`	`public class EncapsulateFieldModel : IRefactoringModel`
`10`	`15`	`{`
`11`	`16`	`public EncapsulateFieldModel(EncapsulateFieldUseBackingFieldModel backingFieldModel,`
Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,10 @@ public interface IEncapsulateFieldRefactoringActionsProvider`
`15`	`15`	`ICodeOnlyRefactoringAction<EncapsulateFieldInsertNewCodeModel> EncapsulateFieldInsertNewCode { get; }`
`16`	`16`	`}`
`17`	`17`
	`18`	`+ /// <summary>`
	`19`	`+ /// EncapsulateFieldRefactoringActionsProvider reduces the number of EncapsulateField refactoring action`
	`20`	`+ /// constructor parameters providing refactoring actions common to the aggregated EncapsulateFieldRefactoringActions`
	`21`	`+ /// </summary>`
`18`	`22`	`public class EncapsulateFieldRefactoringActionsProvider : IEncapsulateFieldRefactoringActionsProvider`
`19`	`23`	`{`
`20`	`24`	`private readonly ReplaceReferencesRefactoringAction _replaceReferences;`