From 00c60ba0ad629ed7e447fcafc2e9ed7b6364da53 Mon Sep 17 00:00:00 2001
From: Daniel Kraus <krada@gmx.net>
Date: Tue, 11 Aug 2015 19:51:23 +0200
Subject: [PATCH] Comment on serialization.

---
 README.md                                     | 27 +++++++++++++++++++
 zaaReloaded2/Controller/SettingsRepository.cs | 22 +++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/README.md b/README.md
index e5dec80..6278f40 100644
--- a/README.md
+++ b/README.md
@@ -174,4 +174,31 @@ oder nicht-normalen Parametern oder immer mit ausgegeben werden:
 Die Markierung besonderer Parameter erfolgt in der Textdatei, aus der
 das `zaaReloaded2.Thesaurus.Parameters` generiert wird (s.o.).
 
+
+## Serialisierung
+
+Um das Stil-Repositorium (`zaaReloaded2.Controller.SettingsRepository`)
+in den Assembly-Properties speichern zu können und für den Im- und
+Export von Stilen werden die in .NET eingebauten
+Serialisierungs-Strukturen genutzt. Weil es mit der Verwendung eines
+`XmlSerializer`s Probleme gab, weil der `XmlSerializer` nicht mit
+Interface-Eigenschaften umgehen kann, wurde zunächst für alle Klassen,
+die serialisiert werden müssen (`SettingsRepository`,
+`zaaReloaded2.Controller.Settings` und die von
+`zaaReloaded2.Controller.Elements.ElementBase` abgeleiteten Klassen) das
+Interface `ISerializable` implementiert. Das hat aber auch nicht dazu
+geführt, daß der `XmlSerializer` die Klassen serialisierte, so daß
+jetzt der `SoapFormatter` verwendet wird. Der stört sich nicht an
+Interface-Eigenschaften und produziert auch XML, wenngleich im etwas
+komplizierten [SOAP][]-Format.
+
+Um das `SettingsRepository` in den Assembly-Properties zu persistieren,
+muß das serialisierte XML noch in einen Base64-kodierten String
+umgewandelt werden, damit das SOAP-XML nicht mit dem XML der
+Assembly-Properties ins Gehege kommt (siehe
+`zaaReloaded2.Controller.SettingsRepository.Load()` und
+`zaaReloaded2.Controller.SettingsRepository.Store()`).
+
+[SOAP]: http://de.wikipedia.org/wiki/SOAP
+
 <!-- vim: set tw=72 sw=2 ts=2 sts=-1 : -->
diff --git a/zaaReloaded2/Controller/SettingsRepository.cs b/zaaReloaded2/Controller/SettingsRepository.cs
index 5f465f8..2bc9960 100755
--- a/zaaReloaded2/Controller/SettingsRepository.cs
+++ b/zaaReloaded2/Controller/SettingsRepository.cs
@@ -44,6 +44,19 @@ namespace zaaReloaded2.Controller
     {
         #region Properties persistence
 
+        /// <summary>
+        /// Loads the SettingsRepository instance that was persisted in
+        /// the assembly properties.
+        /// </summary>
+        /// <returns>SettingsRepository that was last stored in the
+        /// assembly properties, or a newly created SettingsRepository
+        /// if no previously stored exists.</returns>
+        /// <remarks>
+        /// The SettingsRepository is serialized using a SoapFormatter, which
+        /// creates SOAP XML. Since the assembly properties are stored as
+        /// XML as well, the serialized SettingsRepository is converted to
+        /// a base-64 string, which does not mess with the properties XML.
+        /// </remarks>
         public static SettingsRepository Load()
         {
             string s = Properties.Settings.Default.SettingsRepository;
@@ -63,6 +76,15 @@ namespace zaaReloaded2.Controller
             }
         }
 
+        /// <summary>
+        /// Stores the SettingsRepository in the assembly properties.
+        /// </summary>
+        /// <remarks>
+        /// The SettingsRepository is serialized using a SoapFormatter, which
+        /// creates SOAP XML. Since the assembly properties are stored as
+        /// XML as well, the serialized SettingsRepository is converted to
+        /// a base-64 string, which does not mess with the properties XML.
+        /// </remarks>
         public void Store()
         {
             MemoryStream stream = new MemoryStream();