Renamed relevant references of relationships to associations

JeremyCaney · JeremyCaney · commit 0e32098b0783 · 2021-02-06T15:30:25.000-08:00
As we've worked to disambiguate the term "relationships" from "collections" (1daf799) and "relationships" (191262a) by establishing the more general term "associations", we should update the XML Docs to maintain this nomenclature. Most of these are not references to e.g. the `AssociationTypes` enum, but rather discuss the concept in more abstract terms. By consistently using "associations" here instead of "relationships", we help reinforce the preferred vocabulary, and reduce ambiguities. This update required care to differentiate between references to "relationship" that referred to the broader concept, and references to "relationship" that referred, specifically, to e.g. `Topic.Relationships`, as the latter should be retained.
diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs
@@ -39,12 +39,12 @@ internal static class SqlDataReaderExtensions {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Given a <see cref="IDataReader"/> from a call to the <c>GetTopics</c> stored procedure, will extract a list of
-    ///   topics and populate their attributes, relationships, and children.
+    ///   topics and populate their attributes, associations, and children.
     /// </summary>
     /// <param name="reader">The <see cref="IDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
     /// <param name="referenceTopic">
-    ///   When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic references
-    ///   and relationships, including <see cref="Topic.Parent"/>, are integrated with existing entities.
+    ///   When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic
+    ///   associations—such as references, relationships, and <see cref="Topic.Parent"/>—are integrated with existing entities.
     /// </param>
     /// <param name="markDirty">
     ///   Specified whether the target collection value should be marked as dirty, assuming the value changes. By default, it
@@ -394,7 +394,7 @@ private static void SetRelationships(this IDataReader reader, TopicIndex topics,
     ///   Adds topic references to their associated topics.
     /// </summary>
     /// <remarks>
-    ///   Topics can be cross-referenced with each other topics via a one-to-one relationships. Once the topics are populated in
+    ///   Topics can be cross-referenced with each other topics via a one-to-one associations. Once the topics are populated in
     ///   memory, loop through the data to create these associations.
     /// </remarks>
     /// <param name="reader">The <see cref="IDataReader"/> with output from the <c>GetTopics</c> stored procedure.</param>
@@ -411,7 +411,7 @@ private static void SetReferences(this IDataReader reader, TopicIndex topics, bo
       | Identify attributes
       \-----------------------------------------------------------------------------------------------------------------------*/
       var sourceTopicId         = reader.GetTopicId("Source_TopicID");
-      var relationshipKey       = reader.GetString("ReferenceKey");
+      var referenceKey          = reader.GetString("ReferenceKey");
       var targetTopicId         = reader.GetNullableTopicId("Target_TopicID");
 
       /*------------------------------------------------------------------------------------------------------------------------
@@ -432,9 +432,9 @@ private static void SetReferences(this IDataReader reader, TopicIndex topics, bo
       }
 
       /*------------------------------------------------------------------------------------------------------------------------
-      | Set relationship on object
+      | Set reference on object
       \-----------------------------------------------------------------------------------------------------------------------*/
-      current.References.SetValue(relationshipKey, referenced, markDirty);
+      current.References.SetValue(referenceKey, referenced, markDirty);
 
     }
 
diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs
@@ -207,10 +207,10 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic
       );
 
       /*------------------------------------------------------------------------------------------------------------------------
-      | Clear relationships, topic references
+      | Clear associations
       >-------------------------------------------------------------------------------------------------------------------------
       | Because we don't (currently) track version as part of the .NET data model for relationships or topic references, there's
-      | no easy way to determine if a relationship should be deleted when doing a rollback. As such, existing relationships
+      | no easy way to determine if an association should be deleted when doing a rollback. As such, existing associations
       | should be deleted, assuming a `referenceTopic` is passed, and it contains the `topicId`.
       \-----------------------------------------------------------------------------------------------------------------------*/
       var topic                 = (Topic?)null;
@@ -375,7 +375,7 @@ bool persistRelationships
       /*------------------------------------------------------------------------------------------------------------------------
       | Detect whether anything has changed
       >-------------------------------------------------------------------------------------------------------------------------
-      | If no relationships have changed, and no attributes values have changed, and there aren't any mismatched attributes in
+      | If no associations have changed, and no attributes values have changed, and there aren't any mismatched attributes in
       | their respective lists, then there isn't anything new to persist to the database, and thus no benefit to executing the
       | current command. A more aggressive version of this would wrap much of the below logic in this, but this is just meant
       | as a quick fix to reduce the overhead of recursive saves.
diff --git a/OnTopic.Tests/BindingModels/InvalidRelationshipBaseTypeTopicBindingModel.cs b/OnTopic.Tests/BindingModels/InvalidRelationshipBaseTypeTopicBindingModel.cs
@@ -14,7 +14,7 @@ namespace OnTopic.Tests.BindingModels {
   | BINDING MODEL: RELATIONSHIP BASE TYPE TOPIC (INVALID)
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Provides a custom binding model with an invalid base type for a relationship—i.e., one that doesn't implement the <see
+  ///   Provides a custom binding model with an invalid base type for an association—i.e., one that doesn't implement the <see
   ///   cref="IRelatedTopicBindingModel"/>. An <see cref="InvalidOperationException"/> should be thrown when it is mapped.
   /// </summary>
   /// <remarks>
diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs
@@ -298,8 +298,8 @@ public void BaseTopic_UpdateValue_ReturnsExpectedValue() {
     | TEST: BASE TOPIC: RESAVED VALUE: RETURNS EXPECTED VALUE
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Sets a base topic to an unsaved topic entity, then saves the entity and reestablishes the relationship. Ensures
-    ///   that the base topic is correctly set as a <see cref="Topic.References"/> entry.
+    ///   Sets a base topic to an unsaved topic entity, then saves the entity and reestablishes the reference. Ensures that the
+    ///   base topic is correctly set as a <see cref="Topic.References"/> entry.
     /// </summary>
     [TestMethod]
     public void BaseTopic_ResavedValue_ReturnsExpectedValue() {
diff --git a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs
@@ -135,7 +135,7 @@ public ReadOnlyTopicCollection GetAllTopics() =>
       new(Source.SelectMany(list => list.Values).Distinct().ToList());
 
     /// <summary>
-    ///   Retrieves a list of all related <see cref="Topic"/> objects, independent of relationship key, filtered by content
+    ///   Retrieves a list of all related <see cref="Topic"/> objects, independent of key, filtered by content
     ///   type.
     /// </summary>
     /// <returns>
diff --git a/OnTopic/Collections/Specialized/TopicMultiMap.cs b/OnTopic/Collections/Specialized/TopicMultiMap.cs
@@ -119,7 +119,7 @@ public bool Remove(string key, Topic topic) {
       }
 
       /*------------------------------------------------------------------------------------------------------------------------
-      | Remove relationship
+      | Remove topic
       \-----------------------------------------------------------------------------------------------------------------------*/
       topics.Remove(topic);
 
diff --git a/OnTopic/Mapping/Annotations/AssociationTypes.cs b/OnTopic/Mapping/Annotations/AssociationTypes.cs
@@ -101,7 +101,7 @@ public enum AssociationTypes {
     | ALL
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Map all relationship types.
+    ///   Map all association types.
     /// </summary>
     All = Parents | Children | Relationships | IncomingRelationships | MappedCollections | References
 
diff --git a/OnTopic/Mapping/Annotations/CollectionAttribute.cs b/OnTopic/Mapping/Annotations/CollectionAttribute.cs
@@ -10,14 +10,15 @@ namespace OnTopic.Mapping.Annotations {
   | ATTRIBUTE: COLLECTION
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Provides the <see cref="ITopicMappingService"/> with instructions as to which key to follow for the relationship.
+  ///   Provides the <see cref="ITopicMappingService"/> with instructions as to which collection to map to.
   /// </summary>
   /// <remarks>
   ///   <para>
   ///     By default, <see cref="ITopicMappingService"/> implementations will attempt to map a collection property to the first
-  ///     relationship it finds with a key that matches the property name. For example, if a property is named "Categories" it
-  ///     will first look in <see cref="Topic.Relationships"/> for a relationship named "Categories", then it will search <see
-  ///     cref="Topic.Children"/> for a set of nested topics, and finally <see cref="Topic.IncomingRelationships"/>.
+  ///     collection it finds with a key that matches the property name. For example, if a property is named <c>Categories</c>
+  ///     it will first look in <see cref="Topic.Relationships"/> for a relationship named <c>Categories</c>, then it will
+  ///     search <see cref="Topic.References"/>, then <see cref="Topic.Children"/> for a set of nested topics, and finally <see
+  ///     cref="Topic.IncomingRelationships"/>.
   ///   </para>
   ///   <para>
   ///     This attribute instructs the <see cref="ITopicMappingService"/> to instead look for a specified key. This allows the
@@ -36,7 +37,7 @@ public sealed class CollectionAttribute : System.Attribute {
     /// <summary>
     ///   Annotates a property with the <see cref="CollectionAttribute"/> by providing an <paramref name="key"/>.
     /// </summary>
-    /// <param name="key">The key value of the relationships associated with the current property.</param>
+    /// <param name="key">The key value of the collection associated with the current property.</param>
     public CollectionAttribute(string key) {
       TopicFactory.ValidateKey(key, false);
       Key = key;
@@ -45,7 +46,7 @@ public CollectionAttribute(string key) {
     /// <summary>
     ///   Annotates a property with the <see cref="CollectionAttribute"/> by providing the <see cref="CollectionType"/>.
     /// </summary>
-    /// <param name="type">Optional. The type of collection the relationship is associated with.</param>
+    /// <param name="type">Optional. The type of collection the collection is associated with.</param>
     public CollectionAttribute(CollectionType type = CollectionType.Any) {
       Type = type;
     }
diff --git a/OnTopic/Mapping/Annotations/FilterByAttributeAttribute.cs b/OnTopic/Mapping/Annotations/FilterByAttributeAttribute.cs
@@ -13,10 +13,9 @@ namespace OnTopic.Mapping.Annotations {
   ///   Flags that a collection property should be filtered by a specified <c>attributeKey</c> and <c>attributeValue</c>.
   /// </summary>
   /// <remarks>
-  ///   By default, <see cref="ITopicMappingService"/> will add any corresponding relationships to a collection, assuming they
-  ///   are assignable to the collection's base type. With the <c>[FilterByAttribute(attributeKey, attributeValue)]</c>
-  ///   attribute, the collection will instead be filtered to only those topics that have the specified attribute value
-  ///   assigned.
+  ///   By default, <see cref="ITopicMappingService"/> will add any corresponding topics to a collection, assuming they are
+  ///   assignable to the collection's base type. With the <c>[FilterByAttribute(attributeKey, attributeValue)]</c> attribute,
+  ///   the collection will instead be filtered to only those topics that have the specified attribute value assigned.
   /// </remarks>
   [System.AttributeUsage(System.AttributeTargets.Property, AllowMultiple=true, Inherited=true)]
   public sealed class FilterByAttributeAttribute : System.Attribute {
diff --git a/OnTopic/Mapping/Annotations/FilterByContentType.cs b/OnTopic/Mapping/Annotations/FilterByContentType.cs
@@ -13,9 +13,9 @@ namespace OnTopic.Mapping.Annotations {
   ///   Flags that a collection property should be filtered by a specified <c>ContentType</c>.
   /// </summary>
   /// <remarks>
-  ///   By default, <see cref="ITopicMappingService"/> will add any corresponding relationships to a collection, assuming they
-  ///   are assignable to the collection's base type. With the <c>[FilterByContentType(contentType)]</c> attribute, the
-  ///   collection will instead be filtered to only those topics that have the specified content type.
+  ///   By default, <see cref="ITopicMappingService"/> will add any corresponding topic to a collection, assuming they are
+  ///   assignable to the collection's base type. With the <c>[FilterByContentType(contentType)]</c> attribute, the collection
+  ///   will instead be filtered to only those topics that have the specified content type.
   /// </remarks>
   [System.AttributeUsage(System.AttributeTargets.Property, AllowMultiple=true, Inherited=true)]
   public sealed class FilterByContentTypeAttribute : System.Attribute {
diff --git a/OnTopic/Mapping/Annotations/FlattenAttribute.cs b/OnTopic/Mapping/Annotations/FlattenAttribute.cs
@@ -16,11 +16,10 @@ namespace OnTopic.Mapping.Annotations {
   /// <remarks>
   ///   <para>
   ///     By default, <see cref="ITopicMappingService"/> will populate all items in a collection—and, if 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
-  ///     results.
+  ///     cref="IncludeAttribute"/> is defined, then also include their specified associations. 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 results.
   ///   </para>
   /// </remarks>
   [System.AttributeUsage(System.AttributeTargets.Property)]
diff --git a/OnTopic/Mapping/Annotations/MapToParentAttribute.cs b/OnTopic/Mapping/Annotations/MapToParentAttribute.cs
@@ -16,7 +16,7 @@ namespace OnTopic.Mapping.Annotations {
   ///   the provided key.
   /// </summary>
   /// <remarks>
-  ///   By default, complex property objects that don't map to known attributes (e.g., a compatible property) or relationships
+  ///   By default, complex property objects that don't map to known attributes (e.g., a compatible property) or associations
   ///   are bypassed. The <see cref="MapToParentAttribute"/> informs the <see cref="IReverseTopicMappingService"/> to treat the
   ///   properties of such complex objects as members of the parent <see cref="Topic"/>. By default, these will be prefixed by
   ///   the name of the property that the complex object is assigned to. Optionally, however, this may be overwritten—including
diff --git a/OnTopic/Mapping/Internal/PropertyConfiguration.cs b/OnTopic/Mapping/Internal/PropertyConfiguration.cs
diff --git a/OnTopic/Mapping/Reverse/IReverseTopicMappingService.cs b/OnTopic/Mapping/Reverse/IReverseTopicMappingService.cs
diff --git a/OnTopic/Models/IRelatedTopicBindingModel.cs b/OnTopic/Models/IRelatedTopicBindingModel.cs
diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs
diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs
diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs

Original file line number	Diff line number	Diff line change
`@@ -119,7 +119,7 @@ public bool Remove(string key, Topic topic) {`
`119`	`119`	`}`
`120`	`120`
`121`	`121`	`/*------------------------------------------------------------------------------------------------------------------------`
`122`		`- \| Remove relationship`
	`122`	`+ \| Remove topic`
`123`	`123`	`\-----------------------------------------------------------------------------------------------------------------------*/`
`124`	`124`	`topics.Remove(topic);`
`125`	`125`