Changeset 3028

Timestamp:

03/15/10 12:01:10 (14 years ago)

Author:

epitzer

Message:

add more API docs (#548)

Location:

trunk/sources/HeuristicLab.Persistence/3.3/Default/Xml

Files:

• XmlGenerator.cs (modified) (5 diffs)
• XmlParser.cs (modified) (8 diffs)

trunk/sources/HeuristicLab.Persistence/3.3/Default/Xml/XmlGenerator.cs

@@ -189 +189 @@
     }
 
+    /// <summary>
+    /// Formats the specified type cache.
+    /// </summary>
+    /// <param name="typeCache">The type cache.</param>
+    /// <returns>An enumerable of formatted type cache tags.</returns>
     public IEnumerable<string> Format(List<TypeMapping> typeCache) {
       yield return CreateNodeStart(XmlStringConstants.TYPECACHE);
@@ -211 +216 @@
     /// <summary>
     /// Serialize an object into a file.
-    /// 
     /// The XML configuration is obtained from the <c>ConfigurationService</c>.
     /// Needed assemblies are not included.
     /// </summary>
+    /// <param name="o">The object.</param>
+    /// <param name="filename">The filename.</param>
     /// <param name="compression">ZIP file compression level</param>
     public static void Serialize(object o, string filename, int compression) {
@@ -220 +226 @@
     }
 
+    /// <summary>
+    /// Serializes the specified object into a file.
+    /// Needed assemblies are not included, ZIP compression level is set to 5.
+    /// </summary>
+    /// <param name="obj">The object.</param>
+    /// <param name="filename">The filename.</param>
+    /// <param name="config">The configuration.</param>
     public static void Serialize(object obj, string filename, Configuration config) {
       Serialize(obj, filename, config, false, 5);
     }
 
+    /// <summary>
+    /// Serializes the specified object into a file.
+    /// </summary>
+    /// <param name="obj">The object.</param>
+    /// <param name="filename">The filename.</param>
+    /// <param name="config">The configuration.</param>
+    /// <param name="includeAssemblies">if set to <c>true</c> include needed assemblies.</param>
+    /// <param name="compression">The ZIP compression level.</param>
     public static void Serialize(object obj, string filename, Configuration config, bool includeAssemblies, int compression) {      
       try {
@@ -278 +299 @@
     }
 
+    /// <summary>
+    /// Serializes the specified object into a stream using the <see cref="XmlFormat"/>
+    /// obtained from the <see cref="ConfigurationService"/>.
+    /// </summary>
+    /// <param name="obj">The object.</param>
+    /// <param name="stream">The stream.</param>
     public static void Serialize(object obj, Stream stream) {
       Serialize(obj, stream, ConfigurationService.Instance.GetConfiguration(new XmlFormat()));
@@ -283 +310 @@
 
 
+    /// <summary>
+    /// Serializes the specified object into a stream.
+    /// </summary>
+    /// <param name="obj">The object.</param>
+    /// <param name="stream">The stream.</param>
+    /// <param name="config">The configuration.</param>
     public static void Serialize(object obj, Stream stream, Configuration config) {
       Serialize(obj, stream, config, false);
     }
 
-    public static void Serialize(object obj, Stream stream, Configuration config, bool includeAssemblies) {
-      Serialize(obj, stream, config, includeAssemblies, true);
-    }
-
-    public static void Serialize(object obj, Stream stream, Configuration config, bool includeAssemblies, bool interleaveTypeInfo) {      
+    /// <summary>
+    /// Serializes the specified object into a stream.
+    /// </summary>
+    /// <param name="obj">The object.</param>
+    /// <param name="stream">The stream.</param>
+    /// <param name="config">The configuration.</param>
+    /// <param name="includeAssemblies">if set to <c>true</c> include need assemblies.</param>
+    public static void Serialize(object obj, Stream stream, Configuration config, bool includeAssemblies) {      
       try {
         using (StreamWriter writer = new StreamWriter(new GZipStream(stream, CompressionMode.Compress))) {

trunk/sources/HeuristicLab.Persistence/3.3/Default/Xml/XmlParser.cs

@@ -12 +12 @@
 namespace HeuristicLab.Persistence.Default.Xml {
 
+  /// <summary>
+  /// Main entry point of persistence loading from XML. Use the static
+  /// methods to load from a file or stream.
+  /// </summary>
   public class XmlParser : IEnumerable<ISerializationToken> {
 
@@ -18 +22 @@
     private readonly Dictionary<string, Handler> handlers;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="XmlParser"/> class.
+    /// </summary>
+    /// <param name="input">The input.</param>
     public XmlParser(TextReader input) {
       XmlReaderSettings settings = new XmlReaderSettings {
@@ -35 +43 @@
     }
 
+    /// <summary>
+    /// Returns an enumerator that iterates through the serialization tokens.
+    /// </summary>
+    /// <returns>
+    /// An that can be used to iterate through the collection of serialization tokens.
+    /// </returns>
     public IEnumerator<ISerializationToken> GetEnumerator() {
       while (reader.Read()) {
@@ -52 +66 @@
         }
       }
+    }
+
+    /// <summary>
+    /// Returns an enumerator that iterates through the serialization tokens.
+    /// </summary>
+    /// <returns>
+    /// An that can be used to iterate through the collection of serialization tokens.
+    /// </returns>
+    IEnumerator IEnumerable.GetEnumerator() {
+      return GetEnumerator();
     }
 
@@ -115 +139 @@
     }
 
-    IEnumerator IEnumerable.GetEnumerator() {
-      return GetEnumerator();
-    }
-
+    /// <summary>
+    /// Parses the type cache.
+    /// </summary>
+    /// <param name="reader">The reader.</param>
+    /// <returns>A list of type mapping entries.</returns>
     public static List<TypeMapping> ParseTypeCache(TextReader reader) {
       try {
@@ -139 +164 @@
     }
 
+    /// <summary>
+    /// Deserializes an object from the specified filename.
+    /// </summary>
+    /// <param name="filename">The filename.</param>
+    /// <returns>A fresh object instance</returns>
     public static object Deserialize(string filename) {
       using (ZipFile file = new ZipFile(filename)) {
@@ -145 +175 @@
     }
 
+    /// <summary>
+    /// Deserializes the specified filename.
+    /// </summary>
+    /// <typeparam name="T">object type expected from the serialized file</typeparam>
+    /// <param name="filename">The filename.</param>
+    /// <returns>A fresh object of type T</returns>
+    public static T Deserialize<T>(string filename) {
+      return (T)Deserialize(filename);
+    }
+
+
+    /// <summary>
+    /// Deserializes an object from the specified stream.
+    /// </summary>
+    /// <param name="stream">The stream.</param>
+    /// <returns>A fresh object instance.</returns>
     public static object Deserialize(Stream stream) {
       try {
@@ -157 +203 @@
         throw new PersistenceException("Unexpected exception during deserialization", x);
       }
+    }
+
+    /// <summary>
+    /// Deserializes an object from the specified stream.
+    /// </summary>
+    /// <typeparam name="T">object type expected from the serialized stream</typeparam>
+    /// <param name="stream">The stream.</param>
+    /// <returns>A fresh object instance.</returns>
+    public static T Deserialize<T>(Stream stream) {
+      return (T)Deserialize(stream);
     }