added some Javadoc explaining the limitations and capabilities of the SettingsToJsonSerializer

java/com.sap.sse.common/src/com/sap/sse/common/settings/SettingsToJsonSerializer.java

@@ -10,6 +10,21 @@ import java.util.Map.Entry;
 import org.json.simple.JSONArray;
 import org.json.simple.JSONObject;
 
+/**
+ * Serializes a {@link Settings} object to a {@link JSONObject}. All setting types are supported as top-level entities.
+ * Nesting of {@link Settings} is generally supported. For example, a {@link Settings} object can be contains as one
+ * setting within another {@link Settings} object. However, when nesting {@link EnumSetting} objects within a
+ * {@link ListSetting} then it is mandatory to put this {@link ListSetting} object into a {@link Settings} object's
+ * {@link Settings#getNonDefaultSettings()}, such as into a {@link MapSettings} object. The technical reason for this
+ * limitation is that the {@link Class} object for the enumeration type must be stored with the serialized format in
+ * order to re-construct the enumeration literals of the correct type. For readability of the produced JSON output,
+ * this implementation chooses to store the enumeration class's name in a special property that is sibling of the
+ * enumeration property. A {@link ListSetting} object does not contain named properties and therefore does not allow
+ * us to add such a property easily.
+ * 
+ * @author Axel Uhl (D043530)
+ *
+ */
 public class SettingsToJsonSerializer {
     private final static String TYPE_PROPERTY_SUFFIX = "___TYPE";
     private final static char TYPE_PROPERTY_SUFFIX_ESCAPE = ':';