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

Timestamp:

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

Author:

epitzer

Message:

Update API docs. (#548)

Location:

trunk/sources/HeuristicLab.Persistence/3.3/Interfaces

Files:

• ICompositeSerializer.cs (modified) (4 diffs)
• IFormat.cs (modified) (1 diff)
• IPrimitiveSerializer.cs (modified) (2 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);
   }

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

@@ -8 +8 @@
   /// </summary>
   public interface IFormat {
+
+    /// <summary>
+    /// Gets the name.
+    /// </summary>
+    /// <value>The name.</value>
     string Name { get; }
+
+    /// <summary>
+    /// Gets the type of the serial data.
+    /// </summary>
+    /// <value>The type of the serial data.</value>
     Type SerialDataType { get; }
   }

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

@@ -9 +9 @@
   /// </summary>
   public interface IPrimitiveSerializer {
+
+    /// <summary>
+    /// Gets the type of the serial data.
+    /// </summary>
+    /// <value>The type of the serial data.</value>
     Type SerialDataType { get; }
+
+    /// <summary>
+    /// Gets the source type.
+    /// </summary>
+    /// <value>The type of the source.</value>
     Type SourceType { get; }
+
+    /// <summary>
+    /// Creates a serialized representation of the provided object.
+    /// </summary>
+    /// <param name="o">The object.</param>
+    /// <returns>A serialized version of the object.</returns>
     ISerialData Format(object o);
-    object Parse(ISerialData o);
+
+
+    /// <summary>
+    /// Creates a fresh object instance using the serializes data..
+    /// </summary>
+    /// <param name="data">The data.</param>
+    /// <returns>A fresh object instance.</returns>
+    object Parse(ISerialData data);
   }
 
@@ -20 +43 @@
   /// of implementing this interface.
   /// </summary>
+  /// <typeparam name="Source">The source type.</typeparam>
+  /// <typeparam name="SerialData">The serialized data type.</typeparam>
   public interface IPrimitiveSerializer<Source, SerialData> : IPrimitiveSerializer where SerialData : ISerialData {
+
+    /// <summary>
+    /// Creates a serialized version of the provided object.
+    /// </summary>
+    /// <param name="o">The object.</param>
+    /// <returns>A serialized version of the object.</returns>
     SerialData Format(Source o);
-    Source Parse(SerialData t);
+
+
+    /// <summary>
+    /// Creates a fresh object instance from the serialized data
+    /// </summary>
+    /// <param name="data">The data.</param>
+    /// <returns>A fresh object instance.</returns>
+    Source Parse(SerialData data);
   }