diff --git a/JSONAPI/Core/IModelManager.cs b/JSONAPI/Core/IModelManager.cs index 8f5a0305..8eb7cc2e 100644 --- a/JSONAPI/Core/IModelManager.cs +++ b/JSONAPI/Core/IModelManager.cs @@ -7,20 +7,51 @@ namespace JSONAPI.Core { + /// + /// + /// The IModelManager interface defines a set of methods used to introspect + /// model objects for serialization and deserialization purposes. For most users, + /// the provided will be sufficient, + /// but you can also provide your own implementation if needed. + /// + /// + /// One of the reasons for the existence of IModelManager (and the + /// provided implementation ) + /// is to be able to capture and cache the results of operations that can be very + /// expensive due to the use of reflection. Consider caching the results + /// of most of the methods if you use reflection extensively in your own + /// implementation of IModelManager, because these methods will be + /// called by many many times. + /// + /// + /// To use an IModelManager, pass it to . + /// + /// + /// public interface IModelManager { + /// + /// Provides (get-only) access to the instance attached to this IModelManager. + /// Any IModelManager must expose an IPluralizationService through this property for use by the . + /// Usually your IModelManager would accept an instance of IPluralizationService as a contructor parameter, but it might also + /// always create one of a particular class. It would also be possible for an IModelManager implementation to also implement + /// IPluralizationService and simply return itself for this property. + /// IPluralizationService PluralizationService { get; } /// + /// /// Returns the property that is treated as the unique identifier in a given class. - /// This is used most importantly by JsonApiFormatter to determine what value to + /// This is used most importantly by to determine what value to /// write when serializing a "Many" relationship as an array of Ids. It is also - /// used to make dummy related objects (with only the Id property set) when - /// deserializing a JSON payload that specifies a related object only by Id. - /// + /// used to make dummy related objects (with only the ID property set) when + /// deserializing a JSON payload that specifies a related object only by ID. + /// + /// /// Rules for determining this may vary by implementation. + /// /// - /// + /// The model class /// The property determined to represent the Id. PropertyInfo GetIdProperty(Type type); @@ -35,14 +66,14 @@ public interface IModelManager /// /// Returns the key that will be used to represent the given property in serialized - /// JSON. Inverse of GetPropertyForJsonKey. + /// JSON. Inverse of . /// /// The serializable property /// The string denoting the given property within a JSON document. string GetJsonKeyForProperty(PropertyInfo propInfo); //TODO: Do we need to have a type parameter here, in case the property is inherited? /// - /// Returns the property corresponding to a given JSON Key. Inverse of GetJsonKeyForProperty. + /// Returns the property corresponding to a given JSON Key. Inverse of . /// /// The Type to find the property on /// The JSON key representing a property @@ -50,11 +81,11 @@ public interface IModelManager PropertyInfo GetPropertyForJsonKey(Type type, string jsonKey); /// - /// Analogue to System.Type.GetProperties(), but made available so that any caching done - /// by an IModelManager can be leveraged to return the results faster. + /// Analogue to , but made available so that any caching done + /// by an IModelManager can be leveraged to return the results faster. /// /// The type to get properties from - /// All properties recognized by the IModelManager. + /// All properties recognized by the IModelManager. //TODO: This needs to include JsonIgnore'd properties, so that they can be found and explicitly included at runtime...confusing? Add another method that excludes these? PropertyInfo[] GetProperties(Type type); @@ -62,16 +93,16 @@ public interface IModelManager /// Determines whether or not the given type will be treated as a "Many" relationship. /// /// The serializable Type - /// True for Array and IEnumerable<T> types, false otherwise. + /// True for Array and types, false otherwise. bool IsSerializedAsMany(Type type); /// - /// Analogue for System.Type.GetElementType, but works for arrays or IEnumerable<T>, + /// Analogue for , but works for arrays or , /// and provides a capture point to cache potentially expensive reflection operations that - /// have to occur repeatedly in JsonApiFormatter. + /// have to occur repeatedly in . /// - /// A type which must be either an Array type or implement IEnumerable<T>. - /// The element type of an Array, or the first generic parameter of an IEnumerable<T>. + /// A type which must be either an Array type or implement . + /// The element type of an Array, or the first generic parameter of an . Type GetElementType(Type manyType); }