Add some documentation to Wrapper.java

Author: rogermb

src/main/java/com/github/theholywaffle/teamspeak3/api/wrapper/Wrapper.java

@@ -30,80 +30,185 @@
 
 import java.util.Map;
 
+/**
+ * A wrapper class around a {@link Map}.
+ * <p>
+ * We use wrapper classes instead of just passing around plain Maps because
+ * </p><ul>
+ * <li>it's more descriptive</li>
+ * <li>there's no confusion between types (e.g. {@code Client} and {@code Channel})</li>
+ * <li>we can create getters for the specific use-cases</li>
+ * <li>we don't have to check for {@code null} each time</li>
+ * </ul>
+ */
 public class Wrapper {
 
 	private final Map<String, String> map;
 
+	/**
+	 * Creates a new wrapper around the given map.
+	 *
+	 * @param map
+	 * 		the Map to abstract, cannot be {@code null}
+	 */
 	public Wrapper(Map<String, String> map) {
 		this.map = map;
 	}
 
+	/**
+	 * Gets the map underlying this {@code Wrapper}.
+	 *
+	 * @return the underlying map
+	 */
 	public Map<String, String> getMap() {
 		return map;
 	}
 
-	public boolean getBoolean(String str) {
-		return getInt(str) == 1;
+	/**
+	 * Gets a property as a boolean from the underlying map.
+	 * Returns {@code true} if the property exists in the map and its value is {@code "1"}.
+	 *
+	 * @param propertyName
+	 * 		the name of the property
+	 *
+	 * @return the boolean value of the property or {@code false} if the property doesn't exist
+	 */
+	public boolean getBoolean(String propertyName) {
+		return getInt(propertyName) == 1;
 	}
 
-	public boolean getBoolean(Property p) {
-		return getBoolean(p.getName());
+	/**
+	 * Gets a property as a boolean from the underlying map.
+	 * Returns {@code true} if the property exists in the map and its value is {@code "1"}.
+	 *
+	 * @param property
+	 * 		the property
+	 *
+	 * @return the boolean value of the property or {@code false} if the property doesn't exist
+	 */
+	public boolean getBoolean(Property property) {
+		return getBoolean(property.getName());
 	}
 
-	public double getDouble(String str) {
-		final String value = get(str);
+	/**
+	 * Gets a property as a double from the underlying map.
+	 * If the property doesn't exist in the underlying map, {@code -1.0} is returned.
+	 *
+	 * @param propertyName
+	 * 		the name of the property
+	 *
+	 * @return the double value of the property or {@code -1.0} if the property doesn't exist
+	 */
+	public double getDouble(String propertyName) {
+		final String value = get(propertyName);
 		if (value == null || value.isEmpty()) {
 			return -1D;
 		}
 		return Double.valueOf(value);
 	}
 
-	public double getDouble(Property p) {
-		return getDouble(p.getName());
+	/**
+	 * Gets a property as a double from the underlying map.
+	 * If the property doesn't exist in the underlying map, {@code -1.0} is returned.
+	 *
+	 * @param property
+	 * 		the property
+	 *
+	 * @return the double value of the property or {@code -1.0} if the property doesn't exist
+	 */
+	public double getDouble(Property property) {
+		return getDouble(property.getName());
 	}
 
-	public long getLong(String str) {
-		final String value = get(str);
+	/**
+	 * Gets a property as a long from the underlying map.
+	 * If the property doesn't exist in the underlying map, {@code -1} is returned.
+	 *
+	 * @param propertyName
+	 * 		the name of the property
+	 *
+	 * @return the long value of the property or {@code -1} if the property doesn't exist
+	 */
+	public long getLong(String propertyName) {
+		final String value = get(propertyName);
 		if (value == null || value.isEmpty()) {
 			return -1L;
 		}
 		return Long.valueOf(value);
 	}
 
-	public long getLong(Property p) {
-		return getLong(p.getName());
+	/**
+	 * Gets a property as a long from the underlying map.
+	 * If the property doesn't exist in the underlying map, {@code -1} is returned.
+	 *
+	 * @param property
+	 * 		the property
+	 *
+	 * @return the long value of the property or {@code -1} if the property doesn't exist
+	 */
+	public long getLong(Property property) {
+		return getLong(property.getName());
 	}
 
-	public int getInt(String str) {
-		final String value = get(str);
+	/**
+	 * Gets a property as an integer from the underlying map.
+	 * If the property doesn't exist in the underlying map, {@code -1} is returned.
+	 *
+	 * @param propertyName
+	 * 		the name of the property
+	 *
+	 * @return the integer value of the property or {@code -1} if the property doesn't exist
+	 */
+	public int getInt(String propertyName) {
+		final String value = get(propertyName);
 		if (value == null || value.isEmpty()) {
 			return -1;
 		}
 		return Integer.valueOf(value);
 	}
 
-	public int getInt(Property p) {
-		return getInt(p.getName());
+	/**
+	 * Gets a property as an integer from the underlying map.
+	 * If the property doesn't exist in the underlying map, {@code -1} is returned.
+	 *
+	 * @param property
+	 * 		the property
+	 *
+	 * @return the integer value of the property or {@code -1} if the property doesn't exist
+	 */
+	public int getInt(Property property) {
+		return getInt(property.getName());
 	}
 
 	/**
-	 * Only use this if you know what you are doing.
+	 * Gets a property as a String from the underlying map.
+	 * If the property doesn't exist in the underlying map, an empty String is returned.
+	 *
+	 * @param propertyName
+	 * 		the name of the property
+	 *
+	 * @return the String value of the property or an empty String if the property doesn't exist
 	 */
-	public String get(String str) {
-		final String result = map.get(str);
+	public String get(String propertyName) {
+		final String result = map.get(propertyName);
 		return result != null ? result : "";
 	}
 
 	/**
-	 * Only use this if you know what you are doing.
+	 * Gets a property as a {@code String} from the underlying map.
+	 * If the property doesn't exist in the underlying map, an empty String is returned.
+	 *
+	 * @param property
+	 * 		the property
+	 *
+	 * @return the String value of the property or an empty String if the property doesn't exist
 	 */
-	public String get(Property p) {
-		return get(p.getName());
+	public String get(Property property) {
+		return get(property.getName());
 	}
 
 	@Override
 	public String toString() {
 		return map.toString();
 	}
-
 }