Introduce new isExtendedAttribute parameter to SetValue()

In order for `ITopicRepository` to establish that an `AttributeValue` is an `IsExtendedAttribute`, it needs to be able to pass that value to an overload of `SetValue()`. To handle this, a new, optional `isExtendedAttribute` parameter is appended to the `SetValue()` method to allow callers to specify the `IsExtendedAttribute` property of the underlying `AttributeValue`.

This also requires updating a few XMLDocs which reference the `SetValue() method. Each of those pieces of documentation must be updated to reflect the updated signature and potentially "repaginated" to maintain our 128 character code width standard.

Author: JeremyCaney

OnTopic/Attributes/AttributeValue.cs

@@ -33,7 +33,8 @@ namespace OnTopic.Attributes {
   ///   <para>
   ///     This class is immutable: once it is constructed, the values cannot be changed. To change a value, callers must either
   ///     create a new instance of the <see cref="AttributeValue"/> class or, preferably, call the
-  ///     <see cref="Topic.Attributes"/>'s <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, DateTime?)"/>
+  ///     <see cref="Topic.Attributes"/>'s <see cref="AttributeValueCollection.SetValue(String, String, Boolean?, DateTime?,
+  ///     Boolean?)"/>
   ///     method.
   ///   </para>
   /// </remarks>
@@ -168,13 +169,14 @@ internal AttributeValue(
     /// </summary>
     /// <remarks>
     ///   By default, when a user attempts to update an attribute's value by calling <see
-    ///   cref="AttributeValueCollection.SetValue(String, String, Boolean?, DateTime?)"/>, or when an <see cref="AttributeValue"
-    ///   /> is added to the <see cref="AttributeValueCollection"/>, the <see cref="AttributeValueCollection"/> will
-    ///   automatically attempt to call any corresponding setters on <see cref="Topic"/> (or a derived instance) to ensure that
-    ///   the business logic is enforced. To avoid an infinite loop, however, this is disabled when properties on <see
-    ///   cref="Topic"/> call <see cref="Topic.SetAttributeValue(String, String, Boolean?)"/>. When that happens, the
-    ///   <see cref="EnforceBusinessLogic"/> value is set to false to communicate to the <see cref="AttributeValueCollection"/>
-    ///   that it should not call the local property. This value is only intended for internal use.
+    ///   cref="AttributeValueCollection.SetValue(String, String, Boolean?, DateTime?, Boolean?)"/>, or when an <see
+    ///   cref="AttributeValue"/> is added to the <see cref="AttributeValueCollection"/>, the <see
+    ///   cref="AttributeValueCollection"/> will automatically attempt to call any corresponding setters on <see cref="Topic"/>
+    ///   (or a derived instance) to ensure that the business logic is enforced. To avoid an infinite loop, however, this is
+    ///   disabled when properties on <see cref="Topic"/> call <see cref="Topic.SetAttributeValue(String, String, Boolean?)"/>.
+    ///   When that happens, the <see cref="EnforceBusinessLogic"/> value is set to false to communicate to the <see
+    ///   cref="AttributeValueCollection"/> that it should not call the local property. This value is only intended for internal
+    ///   use.
     /// </remarks>
     /// <requires description="The value from the getter must be specified." exception="T:System.ArgumentNullException">
     ///   !String.IsNullOrWhiteSpace(value)

OnTopic/Collections/AttributeValueCollection.cs

@@ -233,6 +233,7 @@ public bool IsDirty(string name) {
     ///   populating the topic graph from a persistent data store as a means of indicating the current version for each
     ///   attribute. This is used when e.g. importing values to determine if the existing value is newer than the source value.
     /// </param>
+    /// <param name="isExtendedAttribute">Determines if the attribute originated from an extended attributes data store.</param>
     /// <requires
     ///   description="The key must be specified for the AttributeValue key/value pair."
     ///   exception="T:System.ArgumentNullException">
@@ -248,8 +249,14 @@ public bool IsDirty(string name) {
     ///   exception="T:System.ArgumentException">
     ///   !value.Contains(" ")
     /// </requires>
-    public void SetValue(string key, string? value, bool? isDirty = null, DateTime? version = null)
-      => SetValue(key, value, isDirty, true, version);
+    public void SetValue(
+      string key,
+      string? value,
+      bool? isDirty = null,
+      DateTime? version = null,
+      bool? isExtendedAttribute = null
+    )
+      => SetValue(key, value, isDirty, true, version, isExtendedAttribute);
 
     /// <summary>
     ///   Protected helper method that either adds a new <see cref="AttributeValue"/> object or updates the value of an existing
@@ -277,6 +284,7 @@ public void SetValue(string key, string? value, bool? isDirty = null, DateTime?
     ///   populating the topic graph from a persistent data store as a means of indicating the current version for each
     ///   attribute. This is used when e.g. importing values to determine if the existing value is newer than the source value.
     /// </param>
+    /// <param name="isExtendedAttribute">Determines if the attribute originated from an extended attributes data store.</param>
     /// <requires
     ///   description="The key must be specified for the AttributeValue key/value pair."
     ///   exception="T:System.ArgumentNullException">
@@ -292,7 +300,14 @@ public void SetValue(string key, string? value, bool? isDirty = null, DateTime?
     ///   exception="T:System.ArgumentException">
     ///   !value.Contains(" ")
     /// </requires>
-    internal void SetValue(string key, string? value, bool? isDirty, bool enforceBusinessLogic, DateTime? version = null) {
+    internal void SetValue(
+      string key,
+      string? value,
+      bool? isDirty,
+      bool enforceBusinessLogic,
+      DateTime? version = null,
+      bool? isExtendedAttribute = null
+    ) {
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Validate input
@@ -327,7 +342,7 @@ internal void SetValue(string key, string? value, bool? isDirty, bool enforceBus
         else if (originalAttribute.Value != value) {
           markAsDirty = true;
         }
-        var newAttribute = new AttributeValue(key, value, markAsDirty, enforceBusinessLogic, version);
+        var newAttribute = new AttributeValue(key, value, markAsDirty, enforceBusinessLogic, version, isExtendedAttribute);
         this[IndexOf(originalAttribute)] = newAttribute;
       }
 
@@ -345,7 +360,7 @@ internal void SetValue(string key, string? value, bool? isDirty, bool enforceBus
       | Create new attribute value
       \-----------------------------------------------------------------------------------------------------------------------*/
       else {
-        Add(new AttributeValue(key, value, isDirty ?? true, enforceBusinessLogic, version));
+        Add(new AttributeValue(key, value, isDirty ?? true, enforceBusinessLogic, version, isExtendedAttribute));
       }
 
     }
@@ -361,8 +376,8 @@ internal void SetValue(string key, string? value, bool? isDirty, bool enforceBus
     ///   <para>
     ///     If a settable property is available corresponding to the <see cref="AttributeValue.Key"/>, the call should be routed
     ///     through that to ensure local business logic is enforced. This is determined by looking for the "__" prefix, which is
-    ///     set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?)"/>'s enforceBusinessLogic parameter. To
-    ///     avoid an infinite loop, internal setters _must_ call this overload.
+    ///     set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?, Boolean?)"/>'s
+    ///     <c>enforceBusinessLogic</c> parameter. To avoid an infinite loop, internal setters <i>must</i> call this overload.
     ///   </para>
     ///   <para>
     ///     Compared to the base implementation, will throw a specific <see cref="ArgumentException"/> error if a duplicate key
@@ -402,8 +417,8 @@ protected override void InsertItem(int index, AttributeValue item) {
     /// <remarks>
     ///   If a settable property is available corresponding to the <see cref="AttributeValue.Key"/>, the call should be routed
     ///   through that to ensure local business logic is enforced. This is determined by looking for the "__" prefix, which is
-    ///   set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?)"/>'s enforceBusinessLogic parameter. To
-    ///   avoid an infinite loop, internal setters _must_ call this overload.
+    ///     set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?, Boolean?)"/>'s
+    ///     <c>enforceBusinessLogic</c> parameter. To avoid an infinite loop, internal setters <i>must</i> call this overload.
     /// </remarks>
     /// <param name="index">The location that the <see cref="AttributeValue"/> should be set.</param>
     /// <param name="item">The <see cref="AttributeValue"/> object which is being inserted.</param>
@@ -424,8 +439,8 @@ protected override void SetItem(int index, AttributeValue item) {
     /// <remarks>
     ///   If a settable property is available corresponding to the <see cref="AttributeValue.Key"/>, the call should be routed
     ///   through that to ensure local business logic is enforced. This is determined by looking for the "__" prefix, which is
-    ///   set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?)"/>'s enforceBusinessLogic parameter. To
-    ///   avoid an infinite loop, internal setters _must_ call this overload.
+    ///     set by the <see cref="SetValue(String, String, Boolean?, Boolean, DateTime?, Boolean?)"/>'s
+    ///     <c>enforceBusinessLogic</c> parameter. To avoid an infinite loop, internal setters <i>must</i> call this overload.
     /// </remarks>
     /// <param name="originalAttribute">The <see cref="AttributeValue"/> object which is being inserted.</param>
     /// <param name="settableAttribute">