Changeset 3016 for trunk/sources/HeuristicLab.Persistence/3.3/Interfaces/ICompositeSerializer.cs

Timestamp:

03/14/10 00:42:28 (15 years ago)

Author:

epitzer

Message:

Update API docs. (#548)

File:

• trunk/sources/HeuristicLab.Persistence/3.3/Interfaces/ICompositeSerializer.cs (modified) (4 diffs)

trunk/sources/HeuristicLab.Persistence/3.3/Interfaces/ICompositeSerializer.cs

@@ -5 +5 @@
 namespace HeuristicLab.Persistence.Interfaces {
 
+  /// <summary>
+  /// A composite serializer does not directly transform an object into its
+  /// serialized form. It merely decomposes into other objects, that can
+  /// later be used to recompose the same object.
+  /// </summary>
   public interface ICompositeSerializer {
 
     /// <summary>
     /// Defines the Priorty of this composite serializer. Higher number means
-    /// higher prioriy. Negative numbers are fallback serializers.
+    /// higher prioriy. Negative numbers are fallback serializers that are
+    /// disabled by default.
+    /// 
     /// All default generic composite serializers have priority 100. Specializations
     /// have priority 200 so they will  be tried first. Priorities are
@@ -18 +25 @@
     /// <summary>
     /// Determines for every type whether the composite serializer is applicable.
-    /// </summary>    
+    /// </summary>
+    /// <param name="type">The type.</param>
+    /// <returns>
+    /// <c>true</c> if this instance can serialize the specified type; otherwise, <c>false</c>.
+    /// </returns>
     bool CanSerialize(Type type);
 
@@ -25 +36 @@
     /// ICompositeSerializer.
     /// </summary>
+    /// <param name="type">The type.</param>
+    /// <returns>A string justifying why type cannot be serialized.</returns>
     string JustifyRejection(Type type);
 
     /// <summary>
-    /// Generate MetaInfo necessary for instance creation. (i.e.
-    /// array dimensions).
-    /// </summary>    
+    /// Generate MetaInfo necessary for instance creation. (e.g. dimensions
+    /// necessary for array creation (see <see cref="ArraySerializer"/>).
+    /// </summary>
+    /// <param name="obj">An object.</param>
+    /// <returns>An enumerable of <see cref="Tag"/>s.</returns>
     IEnumerable<Tag> CreateMetaInfo(object obj);
 
     /// <summary>
-    /// Decompose an object into KeyValuePairs, the Key can be null,
+    /// Decompose an object into <see cref="Tag"/>s, the tag name can be null,
     /// the order in which elements are generated is guaranteed to be
     /// the same as they will be supplied to the Populate method.
-    /// </summary>    
+    /// </summary>
+    /// <param name="obj">An object.</param>
+    /// <returns>An enumerable of <see cref="Tag"/>s.</returns>
     IEnumerable<Tag> Decompose(object obj);
 
@@ -43 +60 @@
     /// Create an instance of the object using the provided meta information.
     /// </summary>
-    /// <param name="type"></param>
-    /// <returns></returns>
+    /// <param name="type">A type.</param>
+    /// <param name="metaInfo">The meta information.</param>
+    /// <returns>A fresh instance of the provided type.</returns>
     object CreateInstance(Type type, IEnumerable<Tag> metaInfo);
 
     /// <summary>
-    /// Compose an object from the KeyValuePairs previously generated
-    /// in DeCompose. The order in which the values are supplied is
-    /// the same as they where generated. Keys might be null.
-    /// </summary>    
+    /// Fills an object with values from the previously generated <see cref="Tag"/>s
+    /// in Decompose. The order in which the values are supplied is
+    /// the same as they where generated. <see cref="Tag"/> names might be null.
+    /// </summary>
+    /// <param name="instance">An empty object instance.</param>
+    /// <param name="tags">The tags.</param>
+    /// <param name="type">The type.</param>
     void Populate(object instance, IEnumerable<Tag> tags, Type type);
   }