Reintroduced Save() overload as [Obsolete]

The `Save(topic, isRecursive, isDraft)` signature was updated to remove the `isDraft` parameter. By reintroducing the original overload, we provide instructions to callers of the original method signature. In practice, we don't expect this to be a common scenario, as the `isDraft` functionality was never fully implemented, and is an artifact of OnTopic 2.x.

Unfortunately, an `[Obsolete[]` member of an interface still needs to be implemented on each implementation of that interface. As such, we won't want to persist these for long after the migration to OnTopic 5.0.0. That said, fortunately, we expect all implementations of `ITopicRepository` to implement `ObservableTopicRepository` as a base class and, therefore, can implement these in that one location in order to cover all derived types (e.g., `SqlTopicRepository`, `CachedTopicRepository`, &c.)

As this introduces ambiguities in the XML Doc references, those also needed to be updated to refer explicitly to the signature of the non-obsolete overload. That's probably a best practice anyway, so will be fine even after we remove the obsolete overload.

Author: JeremyCaney

OnTopic/Attributes/AttributeRecord.cs

@@ -93,9 +93,9 @@ public AttributeRecord(
     ///   <para>
     ///     How an attribute is stored in the underlying repository doesn't impact how the attribute is treated as part of the
     ///     object model. By tracking this, however, OnTopic is able to evaluate configuration mismatches during <see
-    ///     cref="ITopicRepository.Save"/>. This allows the <see cref="ITopicRepository"/> to effective handle scenarios where
-    ///     the configuration for an <see cref="AttributeDescriptor"/> has changed prior to the last time a <see cref="Topic"/>
-    ///     was saved, and thus change the location where it is stored.
+    ///     cref="ITopicRepository.Save(Topic, Boolean)"/>. This allows the <see cref="ITopicRepository"/> to effective handle
+    ///     scenarios where the configuration for an <see cref="AttributeDescriptor"/> has changed prior to the last time a <see
+    ///     cref="Topic"/> was saved, and thus change the location where it is stored.
     ///   </para>
     ///   <para>
     ///     This is important because, otherwise, <see cref="ITopicRepository"/> implementations rely primarily on <see

OnTopic/Obsolete/Attributes/AttributeValue.cs

@@ -194,9 +194,9 @@ internal AttributeValue(
     ///   <para>
     ///     How an attribute is stored in the underlying repository doesn't impact how the attribute is treated as part of the
     ///     object model. By tracking this, however, OnTopic is able to evaluate configuration mismatches during <see
-    ///     cref="ITopicRepository.Save"/>. This allows the <see cref="ITopicRepository"/> to effective handle scenarios where
-    ///     the configuration for an <see cref="AttributeDescriptor"/> has changed prior to the last time a <see cref="Topic"/>
-    ///     was saved, and thus change the location where it is stored.
+    ///     cref="ITopicRepository.Save(Topic, Boolean)"/>. This allows the <see cref="ITopicRepository"/> to effective handle
+    ///     scenarios where the configuration for an <see cref="AttributeDescriptor"/> has changed prior to the last time a <see
+    ///     cref="Topic"/> was saved, and thus change the location where it is stored.
     ///   </para>
     ///   <para>
     ///     This is important because, otherwise, <see cref="ITopicRepository"/> implementations rely primarily on <see

OnTopic/Repositories/ITopicRepository.cs

@@ -176,6 +176,10 @@ public interface ITopicRepository {
     /// <exception cref="ArgumentNullException">topic</exception>
     void Save(Topic topic, bool isRecursive = false);
 
+    /// <inheritdoc cref="Save(Topic, Boolean)"/>
+    [Obsolete("The 'isDraft' argument of the Save() method has been removed.")]
+    int Save(Topic topic, bool isRecursive, bool isDraft);
+
     /*==========================================================================================================================
     | METHOD: MOVE
     \-------------------------------------------------------------------------------------------------------------------------*/

OnTopic/Repositories/ObservableTopicRepository.cs

@@ -236,6 +236,10 @@ public event EventHandler<TopicRenameEventArgs>? TopicRenamed {
     /// <inheritdoc />
     public abstract void Save(Topic topic, bool isRecursive = false);
 
+    /// <inheritdoc cref="Save(Topic, Boolean)"/>
+    [Obsolete("The 'isDraft' argument of the Save() method has been removed.")]
+    public int Save(Topic topic, bool isRecursive, bool isDraft) => throw new NotImplementedException();
+
     /*==========================================================================================================================
     | METHOD: MOVE
     \-------------------------------------------------------------------------------------------------------------------------*/

OnTopic/Topic.cs

@@ -684,13 +684,13 @@ public void MarkClean(string key, bool includeCollections) {
     ///     The underlying value of the <see cref="BaseTopic"/> is stored as a topic reference with the <see cref="KeyValuesPair
     ///     {String, Topic}.Key"/> of <c>BaseTopic</c> in <see cref="Topic.References"/>. If the <see cref="Topic"/> hasn't been
     ///     saved, then the reference will be established, but the <c>BaseTopic</c> won't be persisted to the underlying
-    ///     repository upon <see cref="Repositories.ITopicRepository.Save"/>. That said, when <see cref="Repositories.
-    ///     ITopicRepository.Save(Topic, Boolean)"/> is called, the <see cref="BaseTopic"/> will be reevaluated and, if it has
-    ///     subsequently been saved, and the <c>BaseTopic</c> will be updated accordingly. This allows in-memory topic graphs to
-    ///     be constructed, while preventing invalid <see cref="Topic.Id"/>s from being persisted to the underlying data
-    ///     storage. As a result, however, a <see cref="Topic"/> referencing an <see cref="BaseTopic"/> that is unsaved will
-    ///     need to be saved again once the <see cref="BaseTopic"/> has been saved, assuming it's otherwise outside the scope of
-    ///     the original <see cref="Repositories.ITopicRepository.Save(Topic, Boolean)"/> call.
+    ///     repository upon <see cref="Repositories.ITopicRepository.Save(Topic, Boolean)"/>. That said, when <see cref="
+    ///     Repositories.ITopicRepository.Save(Topic, Boolean)"/> is called, the <see cref="BaseTopic"/> will be reevaluated
+    ///     and, if it has subsequently been saved, and the <c>BaseTopic</c> will be updated accordingly. This allows in-memory
+    ///     topic graphs to be constructed, while preventing invalid <see cref="Topic.Id"/>s from being persisted to the
+    ///     underlying data storage. As a result, however, a <see cref="Topic"/> referencing an <see cref="BaseTopic"/> that is
+    ///     unsaved will need to be saved again once the <see cref="BaseTopic"/> has been saved, assuming it's otherwise outside
+    ///     the scope of the original <see cref="Repositories.ITopicRepository.Save(Topic, Boolean)"/> call.
     ///   </para>
     /// </remarks>
     /// <value>The <see cref="Topic"/> that values should be inherited from, if not otherwise available.</value>