From 5675f9fcebfdeb03510c347712df8e9934b362c6 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Mon, 23 May 2022 12:57:33 -0400
Subject: add watcher names to simplify troubleshooting

---
 .../FieldWatchers/ComparableListWatcher.cs         |  7 +++-
 .../FieldWatchers/ComparableWatcher.cs             |  7 +++-
 .../FieldWatchers/ImmutableCollectionWatcher.cs    |  3 ++
 .../FieldWatchers/NetCollectionWatcher.cs          |  7 +++-
 .../FieldWatchers/NetDictionaryWatcher.cs          |  7 +++-
 .../StateTracking/FieldWatchers/NetListWatcher.cs  |  7 +++-
 .../StateTracking/FieldWatchers/NetValueWatcher.cs |  7 +++-
 .../FieldWatchers/ObservableCollectionWatcher.cs   |  7 +++-
 .../StateTracking/FieldWatchers/WatcherFactory.cs  | 45 +++++++++++++---------
 9 files changed, 72 insertions(+), 25 deletions(-)

(limited to 'src/SMAPI/Framework/StateTracking/FieldWatchers')

diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableListWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableListWatcher.cs
index 3d178a36..0b13434a 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableListWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableListWatcher.cs
@@ -26,6 +26,9 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /*********
         ** Accessors
         *********/
+        /// <inheritdoc />
+        public string Name { get; }
+
         /// <inheritdoc />
         public bool IsChanged => this.AddedImpl.Count > 0 || this.RemovedImpl.Count > 0;
 
@@ -40,10 +43,12 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="values">The collection to watch.</param>
         /// <param name="comparer">The equality comparer which indicates whether two values are the same.</param>
-        public ComparableListWatcher(ICollection<TValue> values, IEqualityComparer<TValue> comparer)
+        public ComparableListWatcher(string name, ICollection<TValue> values, IEqualityComparer<TValue> comparer)
         {
+            this.Name = name;
             this.CurrentValues = values;
             this.LastValues = new HashSet<TValue>(comparer);
         }
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableWatcher.cs
index e51c46c1..e2f6c7fd 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableWatcher.cs
@@ -20,6 +20,9 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /*********
         ** Accessors
         *********/
+        /// <inheritdoc />
+        public string Name { get; }
+
         /// <inheritdoc />
         public TValue PreviousValue { get; private set; }
 
@@ -34,10 +37,12 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="getValue">Get the current value.</param>
         /// <param name="comparer">The equality comparer which indicates whether two values are the same.</param>
-        public ComparableWatcher(Func<TValue> getValue, IEqualityComparer<TValue> comparer)
+        public ComparableWatcher(string name, Func<TValue> getValue, IEqualityComparer<TValue> comparer)
         {
+            this.Name = name;
             this.GetValue = getValue;
             this.Comparer = comparer;
             this.CurrentValue = getValue();
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/ImmutableCollectionWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/ImmutableCollectionWatcher.cs
index b46e0b24..9c2ba9bc 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/ImmutableCollectionWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/ImmutableCollectionWatcher.cs
@@ -13,6 +13,9 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /// <summary>A singleton collection watcher instance.</summary>
         public static ImmutableCollectionWatcher<TValue> Instance { get; } = new();
 
+        /// <inheritdoc />
+        public string Name => nameof(ImmutableCollectionWatcher<TValue>);
+
         /// <inheritdoc />
         public bool IsChanged { get; } = false;
 
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetCollectionWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetCollectionWatcher.cs
index e278fa99..1d5e4851 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetCollectionWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetCollectionWatcher.cs
@@ -24,6 +24,9 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /*********
         ** Accessors
         *********/
+        /// <inheritdoc />
+        public string Name { get; }
+
         /// <inheritdoc />
         public bool IsChanged => this.AddedImpl.Count > 0 || this.RemovedImpl.Count > 0;
 
@@ -38,9 +41,11 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="field">The field to watch.</param>
-        public NetCollectionWatcher(NetCollection<TValue> field)
+        public NetCollectionWatcher(string name, NetCollection<TValue> field)
         {
+            this.Name = name;
             this.Field = field;
             field.OnValueAdded += this.OnValueAdded;
             field.OnValueRemoved += this.OnValueRemoved;
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetDictionaryWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetDictionaryWatcher.cs
index a0fcc236..3bd8e09d 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetDictionaryWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetDictionaryWatcher.cs
@@ -31,6 +31,9 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /*********
         ** Accessors
         *********/
+        /// <inheritdoc />
+        public string Name { get; }
+
         /// <inheritdoc />
         public bool IsChanged => this.PairsAdded.Count > 0 || this.PairsRemoved.Count > 0;
 
@@ -45,9 +48,11 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="field">The field to watch.</param>
-        public NetDictionaryWatcher(NetDictionary<TKey, TValue, TField, TSerialDict, TSelf> field)
+        public NetDictionaryWatcher(string name, NetDictionary<TKey, TValue, TField, TSerialDict, TSelf> field)
         {
+            this.Name = name;
             this.Field = field;
 
             field.OnValueAdded += this.OnValueAdded;
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetListWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetListWatcher.cs
index 3badb533..5b6a3e1f 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetListWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetListWatcher.cs
@@ -25,6 +25,9 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /*********
         ** Accessors
         *********/
+        /// <inheritdoc />
+        public string Name { get; }
+
         /// <inheritdoc />
         public bool IsChanged => this.AddedImpl.Count > 0 || this.RemovedImpl.Count > 0;
 
@@ -39,9 +42,11 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="field">The field to watch.</param>
-        public NetListWatcher(NetList<TValue, NetRef<TValue>> field)
+        public NetListWatcher(string name, NetList<TValue, NetRef<TValue>> field)
         {
+            this.Name = name;
             this.Field = field;
             field.OnElementChanged += this.OnElementChanged;
             field.OnArrayReplaced += this.OnArrayReplaced;
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetValueWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetValueWatcher.cs
index d00f4582..e4219dda 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetValueWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetValueWatcher.cs
@@ -17,6 +17,9 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /*********
         ** Accessors
         *********/
+        /// <inheritdoc />
+        public string Name { get; }
+
         /// <inheritdoc />
         public bool IsChanged { get; private set; }
 
@@ -31,9 +34,11 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="field">The field to watch.</param>
-        public NetValueWatcher(NetFieldBase<TValue, TNetField> field)
+        public NetValueWatcher(string name, NetFieldBase<TValue, TNetField> field)
         {
+            this.Name = name;
             this.Field = field;
             this.PreviousValue = field.Value;
             this.CurrentValue = field.Value;
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/ObservableCollectionWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/ObservableCollectionWatcher.cs
index f503c47f..1f95ac89 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/ObservableCollectionWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/ObservableCollectionWatcher.cs
@@ -28,6 +28,9 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /*********
         ** Accessors
         *********/
+        /// <inheritdoc />
+        public string Name { get; }
+
         /// <inheritdoc />
         public bool IsChanged => this.AddedImpl.Count > 0 || this.RemovedImpl.Count > 0;
 
@@ -42,9 +45,11 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="field">The field to watch.</param>
-        public ObservableCollectionWatcher(ObservableCollection<TValue> field)
+        public ObservableCollectionWatcher(string name, ObservableCollection<TValue> field)
         {
+            this.Name = name;
             this.Field = field;
             field.CollectionChanged += this.OnCollectionChanged;
         }
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/WatcherFactory.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/WatcherFactory.cs
index c4a4d0b9..c31be1fc 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/WatcherFactory.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/WatcherFactory.cs
@@ -17,37 +17,41 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ****/
         /// <summary>Get a watcher which compares values using their <see cref="object.Equals(object)"/> method. This method should only be used when <see cref="ForEquatable{T}"/> won't work, since this doesn't validate whether they're comparable.</summary>
         /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="getValue">Get the current value.</param>
-        public static IValueWatcher<T> ForGenericEquality<T>(Func<T> getValue)
+        public static IValueWatcher<T> ForGenericEquality<T>(string name, Func<T> getValue)
             where T : struct
         {
-            return new ComparableWatcher<T>(getValue, new GenericEqualsComparer<T>());
+            return new ComparableWatcher<T>(name, getValue, new GenericEqualsComparer<T>());
         }
 
         /// <summary>Get a watcher for an <see cref="IEquatable{T}"/> value.</summary>
         /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="getValue">Get the current value.</param>
-        public static IValueWatcher<T> ForEquatable<T>(Func<T> getValue)
+        public static IValueWatcher<T> ForEquatable<T>(string name, Func<T> getValue)
             where T : IEquatable<T>
         {
-            return new ComparableWatcher<T>(getValue, new EquatableComparer<T>());
+            return new ComparableWatcher<T>(name, getValue, new EquatableComparer<T>());
         }
 
         /// <summary>Get a watcher which detects when an object reference changes.</summary>
         /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="getValue">Get the current value.</param>
-        public static IValueWatcher<T> ForReference<T>(Func<T> getValue)
+        public static IValueWatcher<T> ForReference<T>(string name, Func<T> getValue)
         {
-            return new ComparableWatcher<T>(getValue, new ObjectReferenceComparer<T>());
+            return new ComparableWatcher<T>(name, getValue, new ObjectReferenceComparer<T>());
         }
 
         /// <summary>Get a watcher for a net collection.</summary>
         /// <typeparam name="T">The value type.</typeparam>
         /// <typeparam name="TSelf">The net field instance type.</typeparam>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="field">The net collection.</param>
-        public static IValueWatcher<T> ForNetValue<T, TSelf>(NetFieldBase<T, TSelf> field) where TSelf : NetFieldBase<T, TSelf>
+        public static IValueWatcher<T> ForNetValue<T, TSelf>(string name, NetFieldBase<T, TSelf> field) where TSelf : NetFieldBase<T, TSelf>
         {
-            return new NetValueWatcher<T, TSelf>(field);
+            return new NetValueWatcher<T, TSelf>(name, field);
         }
 
         /****
@@ -55,18 +59,20 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         ****/
         /// <summary>Get a watcher which detects when an object reference in a collection changes.</summary>
         /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="collection">The observable collection.</param>
-        public static ICollectionWatcher<T> ForReferenceList<T>(ICollection<T> collection)
+        public static ICollectionWatcher<T> ForReferenceList<T>(string name, ICollection<T> collection)
         {
-            return new ComparableListWatcher<T>(collection, new ObjectReferenceComparer<T>());
+            return new ComparableListWatcher<T>(name, collection, new ObjectReferenceComparer<T>());
         }
 
         /// <summary>Get a watcher for an observable collection.</summary>
         /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="collection">The observable collection.</param>
-        public static ICollectionWatcher<T> ForObservableCollection<T>(ObservableCollection<T> collection)
+        public static ICollectionWatcher<T> ForObservableCollection<T>(string name, ObservableCollection<T> collection)
         {
-            return new ObservableCollectionWatcher<T>(collection);
+            return new ObservableCollectionWatcher<T>(name, collection);
         }
 
         /// <summary>Get a watcher for a collection that never changes.</summary>
@@ -78,36 +84,39 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
 
         /// <summary>Get a watcher for a net collection.</summary>
         /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="collection">The net collection.</param>
-        public static ICollectionWatcher<T> ForNetCollection<T>(NetCollection<T> collection)
+        public static ICollectionWatcher<T> ForNetCollection<T>(string name, NetCollection<T> collection)
             where T : class, INetObject<INetSerializable>
         {
-            return new NetCollectionWatcher<T>(collection);
+            return new NetCollectionWatcher<T>(name, collection);
         }
 
         /// <summary>Get a watcher for a net list.</summary>
         /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <param name="collection">The net list.</param>
-        public static ICollectionWatcher<T> ForNetList<T>(NetList<T, NetRef<T>> collection)
+        public static ICollectionWatcher<T> ForNetList<T>(string name, NetList<T, NetRef<T>> collection)
             where T : class, INetObject<INetSerializable>
         {
-            return new NetListWatcher<T>(collection);
+            return new NetListWatcher<T>(name, collection);
         }
 
         /// <summary>Get a watcher for a net dictionary.</summary>
+        /// <param name="name">A name which identifies what the watcher is watching, used for troubleshooting.</param>
         /// <typeparam name="TKey">The dictionary key type.</typeparam>
         /// <typeparam name="TValue">The dictionary value type.</typeparam>
         /// <typeparam name="TField">The net type equivalent to <typeparamref name="TValue"/>.</typeparam>
         /// <typeparam name="TSerialDict">The serializable dictionary type that can store the keys and values.</typeparam>
         /// <typeparam name="TSelf">The net field instance type.</typeparam>
         /// <param name="field">The net field.</param>
-        public static NetDictionaryWatcher<TKey, TValue, TField, TSerialDict, TSelf> ForNetDictionary<TKey, TValue, TField, TSerialDict, TSelf>(NetDictionary<TKey, TValue, TField, TSerialDict, TSelf> field)
+        public static NetDictionaryWatcher<TKey, TValue, TField, TSerialDict, TSelf> ForNetDictionary<TKey, TValue, TField, TSerialDict, TSelf>(string name, NetDictionary<TKey, TValue, TField, TSerialDict, TSelf> field)
             where TKey : notnull
             where TField : class, INetObject<INetSerializable>, new()
             where TSerialDict : IDictionary<TKey, TValue>, new()
             where TSelf : NetDictionary<TKey, TValue, TField, TSerialDict, TSelf>
         {
-            return new NetDictionaryWatcher<TKey, TValue, TField, TSerialDict, TSelf>(field);
+            return new NetDictionaryWatcher<TKey, TValue, TField, TSerialDict, TSelf>(name, field);
         }
     }
 }
-- 
cgit