Renamed [Follow()] to [Include()]

JeremyCaney · JeremyCaney · commit 7c150d81f84b · 2021-02-06T14:24:09.000-08:00
The `[Follow()]` attribute name isn't bad, but it's potentially misleading in that it isn't a recusive instruction. For this reason, it's being renamed to `[Include()]`. Not only does this better communicate that this exclusively impacts the models in the associated property, but not their associations, but it is also more consistent with the Entity Framework's nomenclature for navigation properties—which are effectively synonymous with OnTopic's associations.

While we're not generally striving to maintain feature or identifier parity with Entity Framework, it's useful to leverage familiar terminology when the concepts cleanly map, as is the case here.
diff --git a/OnTopic.Tests/ViewModels/AscendentTopicViewModel.cs b/OnTopic.Tests/ViewModels/AscendentTopicViewModel.cs
@@ -24,7 +24,7 @@ namespace OnTopic.Tests.ViewModels {
   /// </remarks>
   public class AscendentTopicViewModel: KeyOnlyTopicViewModel {
 
-    [Follow(AssociationTypes.Parents)]
+    [Include(AssociationTypes.Parents)]
     public AscendentTopicViewModel? Parent { get; set; }
 
   } //Class
diff --git a/OnTopic.Tests/ViewModels/CircularTopicViewModel.cs b/OnTopic.Tests/ViewModels/CircularTopicViewModel.cs
@@ -19,10 +19,10 @@ namespace OnTopic.Tests.ViewModels {
   /// </remarks>
   public class CircularTopicViewModel {
 
-    [Follow(AssociationTypes.Parents)]
+    [Include(AssociationTypes.Parents)]
     public CircularTopicViewModel? Parent { get; set; }
 
-    [Follow(AssociationTypes.Children | AssociationTypes.Parents)]
+    [Include(AssociationTypes.Children | AssociationTypes.Parents)]
     public Collection<CircularTopicViewModel> Children { get; } = new();
 
   } //Class
diff --git a/OnTopic.Tests/ViewModels/DescendentTopicViewModel.cs b/OnTopic.Tests/ViewModels/DescendentTopicViewModel.cs
@@ -26,7 +26,7 @@ namespace OnTopic.Tests.ViewModels {
   /// </remarks>
   public record DescendentTopicViewModel: TopicViewModel {
 
-    [Follow(AssociationTypes.Children)]
+    [Include(AssociationTypes.Children)]
     public TopicViewModelCollection<DescendentTopicViewModel> Children { get; } = new();
 
   } //Class
diff --git a/OnTopic.Tests/ViewModels/Metadata/ContentTypeDescriptorTopicViewModel.cs b/OnTopic.Tests/ViewModels/Metadata/ContentTypeDescriptorTopicViewModel.cs
@@ -23,7 +23,7 @@ public class ContentTypeDescriptorTopicViewModel {
     public Collection<AttributeDescriptorTopicViewModel> AttributeDescriptors { get; } = new();
 
     [Collection(CollectionType.MappedCollection)]
-    [Follow(AssociationTypes.None)]
+    [Include(AssociationTypes.None)]
     public Collection<ContentTypeDescriptorTopicViewModel> PermittedContentTypes { get; } = new();
 
   } //Class
diff --git a/OnTopic.Tests/ViewModels/RelationTopicViewModel.cs b/OnTopic.Tests/ViewModels/RelationTopicViewModel.cs
@@ -25,7 +25,7 @@ namespace OnTopic.Tests.ViewModels {
   /// </remarks>
   public class RelationTopicViewModel: KeyOnlyTopicViewModel {
 
-    [Follow(AssociationTypes.Children)]
+    [Include(AssociationTypes.Children)]
     public Collection<RelationTopicViewModel> Cousins { get; } = new();
 
   } //Class
diff --git a/OnTopic.Tests/ViewModels/RelationWithChildrenTopicViewModel.cs b/OnTopic.Tests/ViewModels/RelationWithChildrenTopicViewModel.cs
@@ -25,7 +25,7 @@ namespace OnTopic.Tests.ViewModels {
   /// </remarks>
   public class RelationWithChildrenTopicViewModel: RelationTopicViewModel {
 
-    [Follow(AssociationTypes.Relationships)]
+    [Include(AssociationTypes.Relationships)]
     public Collection<RelationWithChildrenTopicViewModel> Children { get; } = new();
 
   } //Class
diff --git a/OnTopic.ViewModels/TopicViewModel.cs b/OnTopic.ViewModels/TopicViewModel.cs
@@ -86,12 +86,12 @@ public record TopicViewModel: ITopicViewModel {
     /// </summary>
     /// <remarks>
     ///   If the current <see cref="TopicViewModel"/> is being mapped as part of another <see cref="TopicViewModel"/>, then the
-    ///   <see cref="Parent"/> property will only be mapped if that association includes a <see cref="FollowAttribute"/> with a
+    ///   <see cref="Parent"/> property will only be mapped if that association includes a <see cref="IncludeAttribute"/> with a
     ///   value including <see cref="AssociationTypes.Parents"/>. If it does, all <see cref="Parent"/> topics will be mapped up
     ///   to the root of the site. No other associations on the <see cref="Parent"/> view models will be mapped, even if they
-    ///   are annotated with a <see cref="FollowAttribute"/>.
+    ///   are annotated with a <see cref="IncludeAttribute"/>.
     /// </remarks>
-    [Follow(AssociationTypes.Parents)]
+    [Include(AssociationTypes.Parents)]
     public TopicViewModel? Parent { get; init; }
 
   } //Class
diff --git a/OnTopic/Mapping/Annotations/AssociationTypes.cs b/OnTopic/Mapping/Annotations/AssociationTypes.cs
@@ -16,7 +16,7 @@ namespace OnTopic.Mapping.Annotations {
   /// </summary>
   /// <remarks>
   ///   <para>
-  ///     The <see cref="TopicMappingService"/> and <see cref="FollowAttribute"/> use the <see cref="AssociationTypes"/> enum to
+  ///     The <see cref="TopicMappingService"/> and <see cref="IncludeAttribute"/> use the <see cref="AssociationTypes"/> enum to
   ///     determine what associations should be mapped—or followed—as part of the mapping process. This helps constrain the
   ///     scope of the object graph to only include the data needed for a given view, or vice verse. That said, the <see cref="
   ///     AssociationTypes"/> enum can be used any place where the code needs to model multiple types of associations relevant
diff --git a/OnTopic/Mapping/Annotations/FlattenAttribute.cs b/OnTopic/Mapping/Annotations/FlattenAttribute.cs
@@ -16,7 +16,7 @@ namespace OnTopic.Mapping.Annotations {
   /// <remarks>
   ///   <para>
   ///     By default, <see cref="ITopicMappingService"/> will populate all items in a collection—and, if the <see
-  ///     cref="FollowAttribute"/> is defined, then also include their specified relationships. The <see
+  ///     cref="IncludeAttribute"/> is defined, then also include their specified relationships. The <see
   ///     cref="FlattenAttribute"/> allows all subsequent children to not only be included, but to be elevated to a single
   ///     list. This can be especially useful when combined with e.g. <see cref="FilterByAttributeAttribute"/> as well as
   ///     strongly-typed collections (e.g., of a specific view model type), as it allows a list to provide, effectively, search
diff --git a/OnTopic/Mapping/Annotations/IncludeAttribute.cs b/OnTopic/Mapping/Annotations/IncludeAttribute.cs
@@ -7,44 +7,42 @@
 namespace OnTopic.Mapping.Annotations {
 
   /*============================================================================================================================
-  | ATTRIBUTE: FOLLOW
+  | ATTRIBUTE: INCLUDE
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Instructs the <see cref="ITopicMappingService"/> to continue following relationships on that property. Optionally
-  ///   specifies which relationships should be followed.
+  ///   Instructs the <see cref="ITopicMappingService"/> to include the specified <see cref="Associations"/> on that property.
   /// </summary>
   /// <remarks>
   ///   <para>
-  ///     By default, <see cref="ITopicMappingService"/> will populate all relationships on the initial data transfer object,
-  ///     but won't continue to do so on related objects. So, for instance, a <c>Children</c> collection will cause all children
-  ///     to be loaded, but the mapper won't populate their <c>Children</c> (assuming that property is set).
+  ///     By default, <see cref="ITopicMappingService"/> will populate all associations on the initial data transfer object,
+  ///     but won't continue to do so on associated objects. So, for instance, a <c>Children</c> collection will cause all
+  ///     children to be loaded, but the mapper won't populate <i>their</i> <c>Children</c> (assuming that property is
+  ///     available).
   ///   </para>
   ///   <para>
-  ///     The <see cref="FollowAttribute"/> overrides this behavior. If set, the <see cref="ITopicMappingService"/> will
-  ///     populate the <see cref="Associations"/> specified on the related topics. By default, it will crawl <i>all</i>
-  ///     relationships, but the <see cref="Associations"/> flag can optionally be used to specify one or multiple
-  ///     relationship types, thus providing fine-tune control.
+  ///     The <see cref="IncludeAttribute"/> overrides this behavior. If set, the <see cref="ITopicMappingService"/> will
+  ///     populate the <see cref="Associations"/> specified on the associated topics.
   ///   </para>
   /// </remarks>
   [System.AttributeUsage(System.AttributeTargets.Property)]
-  public sealed class FollowAttribute : System.Attribute {
+  public sealed class IncludeAttribute : System.Attribute {
 
     /*==========================================================================================================================
     | CONSTRUCTOR
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Annotates a property with the <see cref="FollowAttribute"/> by providing an <paramref name="associations"/>.
+    ///   Annotates a property with the <see cref="IncludeAttribute"/> by providing an <paramref name="associations"/>.
     /// </summary>
     /// <param name="associations">The specific associations that should be crawled.</param>
-    public FollowAttribute(AssociationTypes associations) {
+    public IncludeAttribute(AssociationTypes associations) {
       Associations = associations;
     }
 
     /*==========================================================================================================================
-    | PROPERTY: RELATIONSHIPS
+    | PROPERTY: ASSOCIATIONS
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Gets the type(s) of relationships that should be recursed over.
+    ///   Gets the type(s) of associations that should be recursed over.
     /// </summary>
     public AssociationTypes Associations { get; }
 
diff --git a/OnTopic/Mapping/Internal/PropertyConfiguration.cs b/OnTopic/Mapping/Internal/PropertyConfiguration.cs
@@ -82,7 +82,7 @@ public PropertyConfiguration(PropertyInfo property, string? attributePrefix = ""
       GetAttributeValue<AttributeKeyAttribute>(property,        a => AttributeKey = attributePrefix + a.Key);
       GetAttributeValue<MapToParentAttribute>(property,         a => MapToParent = true);
       GetAttributeValue<MapToParentAttribute>(property,         a => AttributePrefix += (a.AttributePrefix?? property.Name));
-      GetAttributeValue<FollowAttribute>(property,              a => CrawlRelationships = a.Associations);
+      GetAttributeValue<IncludeAttribute>(property,             a => CrawlRelationships = a.Associations);
       GetAttributeValue<FlattenAttribute>(property,             a => FlattenChildren = true);
       GetAttributeValue<MetadataAttribute>(property,            a => MetadataKey = a.Key);
       GetAttributeValue<DisableMappingAttribute>(property,      a => DisableMapping = true);
@@ -291,7 +291,7 @@ public PropertyConfiguration(PropertyInfo property, string? attributePrefix = ""
     ///     one or multiple relationships to be specified for a given property.
     ///   </para>
     ///   <para>
-    ///     The <see cref="CrawlRelationships"/> property corresponds to the <see cref="FollowAttribute.Associations"/>
+    ///     The <see cref="CrawlRelationships"/> property corresponds to the <see cref="IncludeAttribute.Associations"/>
     ///     property. It can be assigned by decorating a DTO property with e.g. <c>[Follow(Relationships.Children)]</c>.
     ///   </para>
     /// </remarks>
diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs
@@ -80,7 +80,7 @@ public TopicMappingService(ITopicRepository topicRepository, ITypeLookupService
     ///   <para>
     ///     This internal version passes a private cache of mapped objects from this run. This helps prevent problems with
     ///     recursion in case <see cref="Topic"/> is referred to multiple times (e.g., a <c>Children</c> collection with
-    ///     <see cref="FollowAttribute"/> set to include <see cref="AssociationTypes.Parents"/>).
+    ///     <see cref="IncludeAttribute"/> set to include <see cref="AssociationTypes.Parents"/>).
     ///   </para>
     /// </remarks>
     /// <param name="topic">The <see cref="Topic"/> entity to derive the data from.</param>
@@ -176,7 +176,7 @@ public TopicMappingService(ITopicRepository topicRepository, ITypeLookupService
     /// <remarks>
     ///   This internal version passes a private cache of mapped objects from this run. This helps prevent problems with
     ///   recursion in case <see cref="Topic"/> is referred to multiple times (e.g., a <c>Children</c> collection with <see cref
-    ///   ="FollowAttribute"/> set to include <see cref="AssociationTypes.Parents"/>).
+    ///   ="IncludeAttribute"/> set to include <see cref="AssociationTypes.Parents"/>).
     /// </remarks>
     /// <returns>
     ///   The target view model with the properties appropriately mapped.
