From 23bb7a24295b155666c8b1d667f0de8235274c03 Mon Sep 17 00:00:00 2001
From: Anairkoen Schno <aaron.cirr.com@gmail.com>
Date: Sat, 14 Dec 2019 18:10:36 -0600
Subject: [PATCH] Added documentation for CustomObjectConverter

---
 IPA.Loader/Config/Stores/Converters.cs     | 35 +++++++++++++++++++++-
 IPA.Loader/Config/Stores/ValueConverter.cs |  7 +++++
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/IPA.Loader/Config/Stores/Converters.cs b/IPA.Loader/Config/Stores/Converters.cs
index 853fd29f..8d92f6f0 100644
--- a/IPA.Loader/Config/Stores/Converters.cs
+++ b/IPA.Loader/Config/Stores/Converters.cs
@@ -34,6 +34,11 @@ namespace IPA.Config.Stores.Converters
                null;
     }
 
+    /// <summary>
+    /// A <see cref="ValueConverter{T}"/> for objects normally serialized to config via <see cref="GeneratedExtension.Generated{T}(Config, bool)"/>.
+    /// </summary>
+    /// <typeparam name="T">the same type parameter that would be passed into <see cref="GeneratedExtension.Generated{T}(Config, bool)"/></typeparam>
+    /// <seealso cref="GeneratedExtension.Generated{T}(Config, bool)"/>
     public class CustomObjectConverter<T> : ValueConverter<T> where T : class
     {
         private interface IImpl
@@ -46,7 +51,7 @@ namespace IPA.Config.Stores.Converters
             private static readonly GeneratedStore.GeneratedStoreCreator creator = GeneratedStore.GetCreator(typeof(T));
 
             public T FromValue(Value value, object parent)
-            { // lots of casting here, but it works i promise
+            { // lots of casting here, but it works i promise (parent can be a non-IGeneratedStore, however it won't necessarily behave then)
                 var obj = creator(parent as GeneratedStore.IGeneratedStore) as U;
                 obj.Deserialize(value);
                 return obj;
@@ -64,15 +69,43 @@ namespace IPA.Config.Stores.Converters
         private static readonly IImpl impl = (IImpl)Activator.CreateInstance(
             typeof(Impl<>).MakeGenericType(GeneratedStore.GetGeneratedType(typeof(T))));
 
+        /// <summary>
+        /// Deserializes <paramref name="value"/> into a <typeparamref name="T"/> with the given <paramref name="parent"/>.
+        /// </summary>
+        /// <param name="value">the <see cref="Value"/> to deserialize</param>
+        /// <param name="parent">the parent object that will own the deserialized value</param>
+        /// <returns>the deserialized value</returns>
+        /// <seealso cref="ValueConverter{T}.FromValue(Value, object)"/>
         public static T Deserialize(Value value, object parent)
             => impl.FromValue(value, parent);
 
+        /// <summary>
+        /// Serializes <paramref name="obj"/> into a <see cref="Value"/> structure, given <paramref name="parent"/>.
+        /// </summary>
+        /// <param name="obj">the object to serialize</param>
+        /// <param name="parent">the parent object that owns <paramref name="obj"/></param>
+        /// <returns>the <see cref="Value"/> tree that represents <paramref name="obj"/></returns>
+        /// <seealso cref="ValueConverter{T}.ToValue(T, object)"/>
         public static Value Serialize(T obj, object parent)
             => impl.ToValue(obj, parent);
 
+        /// <summary>
+        /// Deserializes <paramref name="value"/> into a <typeparamref name="T"/> with the given <paramref name="parent"/>.
+        /// </summary>
+        /// <param name="value">the <see cref="Value"/> to deserialize</param>
+        /// <param name="parent">the parent object that will own the deserialized value</param>
+        /// <returns>the deserialized value</returns>
+        /// <seealso cref="ValueConverter{T}.FromValue(Value, object)"/>
         public override T FromValue(Value value, object parent)
             => impl.FromValue(value, parent);
 
+        /// <summary>
+        /// Serializes <paramref name="obj"/> into a <see cref="Value"/> structure, given <paramref name="parent"/>.
+        /// </summary>
+        /// <param name="obj">the object to serialize</param>
+        /// <param name="parent">the parent object that owns <paramref name="obj"/></param>
+        /// <returns>the <see cref="Value"/> tree that represents <paramref name="obj"/></returns>
+        /// <seealso cref="ValueConverter{T}.ToValue(T, object)"/>
         public override Value ToValue(T obj, object parent)
             => impl.ToValue(obj, parent);
     }
diff --git a/IPA.Loader/Config/Stores/ValueConverter.cs b/IPA.Loader/Config/Stores/ValueConverter.cs
index c0f8e0db..ec5b9628 100644
--- a/IPA.Loader/Config/Stores/ValueConverter.cs
+++ b/IPA.Loader/Config/Stores/ValueConverter.cs
@@ -8,10 +8,17 @@ namespace IPA.Config.Stores
     /// <see cref="GeneratedExtension.Generated{T}(Config, bool)"/>.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// The object returned from <see cref="FromValue(Value, object)"/>, if fed into <see cref="ToValue(object, object)"/>,
     /// should return equivalent <see cref="Value"/> structures. Similarly, if the result of <see cref="ToValue(object, object)"/>
     /// is fed into <see cref="FromValue(Value, object)"/>, the resulting object should be equivalent to the one passed to 
     /// <see cref="ToValue(object, object)"/>.
+    /// </para>
+    /// <para>
+    /// The <c>parent</c> parameter to <see cref="ToValue(object, object)"/> and <see cref="FromValue(Value, object)"/> should
+    /// be (ideally) the the top of the serialization tree, or some other generated object in that tree, rather than some arbitrary
+    /// object in the middle that is not managed by the generatd config system.
+    /// </para>
     /// </remarks>
     public interface IValueConverter
     {