Cleanup and documentation

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/Setting.java

@@ -1,25 +1,48 @@
 package org.dolphinemu.dolphinemu.model.settings;
 
+/**
+ * Abstraction for a setting item as read from / written to Dolphin's configuration ini files.
+ * These files generally consist of a key/value pair, though the type of value is ambiguous and
+ * must be inferred at read-time. The type of value determines which child of this class is used
+ * to represent the Setting.
+ */
 public abstract class Setting
 {
 	private String mKey;
 	private String mSection;
 
+	/**
+	 * Base constructor.
+	 *
+	 * @param key     Everything to the left of the = in a line from the ini file.
+	 * @param section The corresponding recent section header; e.g. [Core] or [Enhancements] without the brackets.
+	 */
 	public Setting(String key, String section)
 	{
 		mKey = key;
 		mSection = section;
 	}
 
+	/**
+	 *
+	 * @return The identifier used to write this setting to the ini file.
+	 */
 	public String getKey()
 	{
 		return mKey;
 	}
 
+	/**
+	 *
+	 * @return The name of the header under which this Setting should be written in the ini file.
+	 */
 	public String getSection()
 	{
 		return mSection;
 	}
 
+	/**
+	 * @return A representation of this Setting's backing value converted to a String (e.g. for serialization).
+	 */
 	public abstract String getValueAsString();
 }

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/SettingSection.java

@@ -2,12 +2,21 @@
 
 import java.util.HashMap;
 
-public class SettingSection
+/**
+ * A semantically-related group of Settings objects. These Settings are
+ * internally stored as a Hashmap.
+ */
+public final class SettingSection
 {
 	private String mName;
 
 	private HashMap<String, Setting> mSettings = new HashMap<>();
 
+	/**
+	 * Create a new SettingSection with no Settings in it.
+	 *
+	 * @param name The header of this section; e.g. [Core] or [Enhancements] without the brackets.
+	 */
 	public SettingSection(String name)
 	{
 		mName = name;
@@ -18,11 +27,23 @@ public String getName()
 		return mName;
 	}
 
+	/**
+	 * Convenience method; inserts a value directly into the backing Hashmap.
+	 *
+	 * @param key The key where the Setting will be inserted.
+	 * @param setting The Setting to be inserted.
+	 */
 	public void putSetting(String key, Setting setting)
 	{
 		mSettings.put(key, setting);
 	}
 
+	/**
+	 * Convenience method; gets a value directly from the backing Hashmap.
+	 *
+	 * @param key Used to retrieve the Setting.
+	 * @return A Setting object (you should probably cast this before using)
+	 */
 	public Setting getSetting(String key)
 	{
 		return mSettings.get(key);

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/CheckBoxSetting.java

@@ -4,7 +4,7 @@
 import org.dolphinemu.dolphinemu.model.settings.BooleanSetting;
 import org.dolphinemu.dolphinemu.model.settings.Setting;
 
-public class CheckBoxSetting extends SettingsItem
+public final class CheckBoxSetting extends SettingsItem
 {
 	private boolean mDefaultValue;
 

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/HeaderSetting.java

@@ -3,7 +3,7 @@
 
 import org.dolphinemu.dolphinemu.model.settings.Setting;
 
-public class HeaderSetting extends SettingsItem
+public final class HeaderSetting extends SettingsItem
 {
 	public HeaderSetting(String key, Setting setting, int titleId, int descriptionId)
 	{

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SettingsItem.java

@@ -2,6 +2,13 @@
 
 import org.dolphinemu.dolphinemu.model.settings.Setting;
 
+/**
+ * ViewModel abstraction for an Item in the RecyclerView powering SettingsFragments.
+ * Each one corresponds to a {@link Setting} object, so this class's subclasses
+ * should vaguely correspond to those subclasses. There are a few with multiple analogues
+ * and a few with none (Headers, for example, do not correspond to anything in the ini
+ * file.)
+ */
 public abstract class SettingsItem
 {
 	public static final int TYPE_HEADER = 0;
@@ -15,47 +22,85 @@ public abstract class SettingsItem
 
 	private Setting mSetting;
 
-	private int mTitleId;
+	private int mNameId;
 	private int mDescriptionId;
 
-	public SettingsItem(String key, String section, Setting setting, int titleId, int descriptionId)
+	/**
+	 * Base constructor. Takes a key / section name in case the third parameter, the Setting,
+	 * is null; in which case, one can be constructed and saved using the key / section.
+	 *
+	 * @param key           Identifier for the Setting represented by this Item.
+	 * @param section       Section to which the Setting belongs.
+	 * @param setting       A possibly-null backing Setting, to be modified on UI events.
+	 * @param nameId        Resource ID for a text string to be displayed as this setting's name.
+	 * @param descriptionId Resource ID for a text string to be displayed as this setting's description.
+	 */
+	public SettingsItem(String key, String section, Setting setting, int nameId, int descriptionId)
 	{
 		mKey = key;
 		mSection = section;
 		mSetting = setting;
-		mTitleId = titleId;
+		mNameId = nameId;
 		mDescriptionId = descriptionId;
 	}
 
+	/**
+	 *
+	 * @return The identifier for the backing Setting.
+	 */
 	public String getKey()
 	{
 		return mKey;
 	}
 
+	/**
+	 *
+	 * @return The header under which the backing Setting belongs.
+	 */
 	public String getSection()
 	{
 		return mSection;
 	}
 
+	/**
+	 *
+	 * @return The backing Setting, possibly null.
+	 */
 	public Setting getSetting()
 	{
 		return mSetting;
 	}
 
+	/**
+	 * Replace the backing setting with a new one. Generally used in cases where
+	 * the backing setting is null.
+	 *
+	 * @param setting A non-null Setting.
+	 */
 	public void setSetting(Setting setting)
 	{
 		mSetting = setting;
 	}
 
+	/**
+	 *
+	 * @return A resource ID for a text string representing this Setting's name.
+	 */
 	public int getNameId()
 	{
-		return mTitleId;
+		return mNameId;
 	}
 
 	public int getDescriptionId()
 	{
 		return mDescriptionId;
 	}
 
+	/**
+	 * Used by {@link org.dolphinemu.dolphinemu.ui.settings.SettingsAdapter}'s onCreateViewHolder()
+	 * method to determine which type of ViewHolder should be created.
+	 *
+	 * @return An integer (ideally, one of the constants defined in this file)
+	 */
 	public abstract int getType();
 }

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SingleChoiceSetting.java

@@ -4,7 +4,7 @@
 import org.dolphinemu.dolphinemu.model.settings.IntSetting;
 import org.dolphinemu.dolphinemu.model.settings.Setting;
 
-public class SingleChoiceSetting extends SettingsItem
+public final class SingleChoiceSetting extends SettingsItem
 {
 	private int mDefaultValue;
 

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SliderSetting.java

@@ -6,7 +6,7 @@
 import org.dolphinemu.dolphinemu.utils.Log;
 import org.dolphinemu.dolphinemu.utils.SettingsFile;
 
-public class SliderSetting extends SettingsItem
+public final class SliderSetting extends SettingsItem
 {
 	private int mMax;
 	private int mDefaultValue;

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SubmenuSetting.java

@@ -2,7 +2,7 @@
 
 import org.dolphinemu.dolphinemu.model.settings.Setting;
 
-public class SubmenuSetting extends SettingsItem
+public final class SubmenuSetting extends SettingsItem
 {
 	private String mMenuKey;
 

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/DividerItemDecoration.java

@@ -14,7 +14,7 @@
  * Implementation from:
  * https://gist.github.com/lapastillaroja/858caf1a82791b6c1a36
  */
-public class DividerItemDecoration extends RecyclerView.ItemDecoration
+public final class DividerItemDecoration extends RecyclerView.ItemDecoration
 {
 
 	private Drawable mDivider;

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityPresenter.java

@@ -13,7 +13,7 @@
 import rx.functions.Action1;
 import rx.schedulers.Schedulers;
 
-public class SettingsActivityPresenter
+public final class SettingsActivityPresenter
 {
 	private SettingsActivityView mView;
 

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityView.java

@@ -4,15 +4,48 @@
 
 import java.util.HashMap;
 
+/**
+ * Abstraction for the Activity that manages SettingsFragments.
+ */
 public interface SettingsActivityView
 {
+	/**
+	 * Show a new SettingsFragment.
+	 *
+	 * @param menuTag    Identifier for the settings group that should be displayed.
+	 * @param addToStack Whether or not this fragment should replace a previous one.
+	 */
 	void showSettingsFragment(String menuTag, boolean addToStack);
 
+	/**
+	 * Called by a contained Fragment to get access to the Setting Hashmap
+	 * loaded from disk, so that each Fragment doesn't need to perform its own
+	 * read operation.
+	 *
+	 * @return A possibly null Hashmap of Settings.
+	 */
 	HashMap<String, SettingSection> getSettings();
 
+	/**
+	 * Used to provide the Activity with a Settings Hashmap if a Fragment already
+	 * has one; for example, if a rotation occurs, the Fragment will not be killed,
+	 * but the Activity will, so the Activity needs to have its Hashmap resupplied.
+	 *
+	 * @param settings The Fragment's Settings hashmap.
+	 */
 	void setSettings(HashMap<String, SettingSection> settings);
 
+	/**
+	 * Called when an asynchronous load operation completes.
+	 *
+	 * @param settings The (possibly null) result of the load operation.
+	 */
 	void onSettingsFileLoaded(HashMap<String, SettingSection> settings);
 
+	/**
+	 * Display a popup text message on screen.
+	 *
+	 * @param message The contents of the onscreen message.
+	 */
 	void showToastMessage(String message);
 }

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsAdapter.java

@@ -30,7 +30,7 @@
 
 import java.util.ArrayList;
 
-public class SettingsAdapter extends RecyclerView.Adapter<SettingViewHolder>
+public final class SettingsAdapter extends RecyclerView.Adapter<SettingViewHolder>
 		implements DialogInterface.OnClickListener, SeekBar.OnSeekBarChangeListener
 {
 	private SettingsFragmentView mView;

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentPresenter.java

@@ -17,7 +17,7 @@
 import java.util.ArrayList;
 import java.util.HashMap;
 
-public class SettingsFragmentPresenter
+public final class SettingsFragmentPresenter
 {
 	private SettingsFragmentView mView;
 

Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentView.java

@@ -9,19 +9,61 @@
 import java.util.ArrayList;
 import java.util.HashMap;
 
+/**
+ * Abstraction for a screen showing a list of settings. Instances of
+ * this type of view will each display a layer of the setting hierarchy.
+ */
 public interface SettingsFragmentView
 {
+	/**
+	 * Called by the containing Activity to notify the Fragment that an
+	 * asynchronous load operation completed.
+	 *
+	 * @param settings The potentially-null result of the load operation.
+	 */
 	void onSettingsFileLoaded(HashMap<String, SettingSection> settings);
 
+	/**
+	 * Pass a settings Hashmap to the containing activity, so that it can
+	 * share the Hashmap with other SettingsFragments; useful so that rotations
+	 * do not require an additional load operation.
+	 *
+	 * @param settings A Hashmap containing all the settings
+	 */
 	void passSettingsToActivity(HashMap<String, SettingSection> settings);
 
+	/**
+	 * Pass an ArrayList to the View so that it can be displayed on screen.
+	 *
+	 * @param settingsList The result of converting the Hashmap to an ArrayList
+	 */
 	void showSettingsList(ArrayList<SettingsItem> settingsList);
 
+	/**
+	 * @return The Fragment's containing activity.
+	 */
 	Activity getActivity();
 
+	/**
+	 * Tell the Fragment to tell the containing Activity to show a new
+	 * Fragment containing a submenu of settings.
+	 *
+	 * @param menuKey Identifier for the settings group that should be shown.
+	 */
 	void loadSubMenu(String menuKey);
 
+	/**
+	 * Tell the Fragment to tell the containing activity to display a toast message.
+	 *
+	 * @param message Text to be shown in the Toast
+	 */
 	void showToastMessage(String message);
 
+	/**
+	 * Have the fragment add a setting to the Hashmap. Useful if the setting
+	 * was missing from the .ini file, but included in the UI.
+	 *
+	 * @param setting The (possibly missing) new setting.
+	 */
 	void addSetting(Setting setting);
 }