From b8ec9bb53aa582613d882d9913a7015623500e33 Mon Sep 17 00:00:00 2001
From: Martin Wittlinger <wittlinger.martin@gmail.com>
Date: Thu, 13 May 2021 17:14:03 +0000
Subject: [PATCH] improve doc for commons package

---
 .../refactorlizar/commons/Settings.java       | 35 +++++++++++++------
 .../refactorlizar/commons/SettingsEntry.java  |  6 ++--
 2 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/commons/src/main/java/edu/kit/kastel/sdq/case4lang/refactorlizar/commons/Settings.java b/commons/src/main/java/edu/kit/kastel/sdq/case4lang/refactorlizar/commons/Settings.java
index d362bc61..bc1102cb 100644
--- a/commons/src/main/java/edu/kit/kastel/sdq/case4lang/refactorlizar/commons/Settings.java
+++ b/commons/src/main/java/edu/kit/kastel/sdq/case4lang/refactorlizar/commons/Settings.java
@@ -1,31 +1,43 @@
 package edu.kit.kastel.sdq.case4lang.refactorlizar.commons;
 
-import com.google.common.flogger.FluentLogger;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;
+import com.google.common.flogger.FluentLogger;
 
 public class Settings {
 
-    private Map<String, MutableSettingsEntry> settings;
+    private Map<String, MutableSettingsEntry> entriesByName;
     private static final FluentLogger logger = FluentLogger.forEnclosingClass();
 
     private Settings() {
-        settings = new HashMap<>();
+        entriesByName = new HashMap<>();
     }
-
+    /**
+     * Returns the entry for the given name. The lookup is case sensitive.
+     * @param key  key for the setting
+     * @return  an optional including the setting if the key was present, empty else.  
+     */
     public Optional<SettingsEntry> getSetting(String key) {
-        return Optional.ofNullable(settings.get(key));
+        return Optional.ofNullable(entriesByName.get(key));
     }
-
+    /**
+     * Sets for the entry for the given key if present. If the key is absent throws an {@link IllegalArgumentException}
+     * @param key  for the wanted setting. mustn't be null.
+     * @param value  the new value for the given setting.
+     */
     public void setValue(String key, String value) {
-        MutableSettingsEntry entry = settings.get(key);
+        MutableSettingsEntry entry = entriesByName.get(key);
         if (entry == null) {
             logger.atWarning().log("For key %s was no entry found", key);
             throw new IllegalArgumentException("Key was no found" + key);
         }
         entry.setValue(value);
     }
+    /**
+     * This class defines an builder for settings objects. Use {@link #build()} for the creation.
+     * A setting consists at least of a key and description. See {@link #addSetting(String, String)} and overloaded methods for possibly setting creation methods.
+     */
 
     public static class SettingsBuilder {
         private Settings settingsObject;
@@ -39,15 +51,18 @@ public SettingsBuilder addSetting(String key, String description) {
         }
 
         public SettingsBuilder addSetting(String key, boolean mandatory, String description) {
-            settingsObject.settings.put(key, MutableSettingsEntry.of(mandatory, description));
+            settingsObject.entriesByName.put(key, MutableSettingsEntry.of(mandatory, description));
             return this;
         }
 
         public SettingsBuilder addSetting(String key, String value, String description) {
-            settingsObject.settings.put(key, MutableSettingsEntry.of(value, description));
+            settingsObject.entriesByName.put(key, MutableSettingsEntry.of(value, description));
             return this;
         }
-
+        /**
+         * Creates the settings object with the previous given settings.
+         * @return  the settings objects. Never null.
+         */
         public Settings build() {
             return settingsObject;
         }
diff --git a/commons/src/main/java/edu/kit/kastel/sdq/case4lang/refactorlizar/commons/SettingsEntry.java b/commons/src/main/java/edu/kit/kastel/sdq/case4lang/refactorlizar/commons/SettingsEntry.java
index 396f4178..094c046a 100644
--- a/commons/src/main/java/edu/kit/kastel/sdq/case4lang/refactorlizar/commons/SettingsEntry.java
+++ b/commons/src/main/java/edu/kit/kastel/sdq/case4lang/refactorlizar/commons/SettingsEntry.java
@@ -1,11 +1,11 @@
 package edu.kit.kastel.sdq.case4lang.refactorlizar.commons;
 /**
- * This defines an immutable settingsentry. An settingsentry is a value with 2 flags, mandatory and
- * defaultvalue flag.
+ * This defines an immutable settings entry. An settings entry is a value with 2 flags: mandatory and
+ * default value flag.
  *
  * <ul>
  *   <li>mandatory: a value must be set
- *   <li>defaultvalue: the current value is the starting value
+ *   <li>default value: the current value is the starting value
  * </ul>
  */
 public interface SettingsEntry {