diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/Setting.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/Setting.java index 2af471e694..8ede2bbe07 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/Setting.java +++ b/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(); } diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/SettingSection.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/SettingSection.java index 7ab9626e65..9f082f6e9d 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/SettingSection.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/SettingSection.java @@ -2,12 +2,21 @@ package org.dolphinemu.dolphinemu.model.settings; 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 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 class SettingSection 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); diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/CheckBoxSetting.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/CheckBoxSetting.java index 510dfdf1af..adc19f8c30 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/CheckBoxSetting.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/CheckBoxSetting.java @@ -4,7 +4,7 @@ package org.dolphinemu.dolphinemu.model.settings.view; 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; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/HeaderSetting.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/HeaderSetting.java index 9ddfae3983..2d5744c555 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/HeaderSetting.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/HeaderSetting.java @@ -3,7 +3,7 @@ package org.dolphinemu.dolphinemu.model.settings.view; 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) { diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SettingsItem.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SettingsItem.java index 1de3663555..4ec62717b7 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SettingsItem.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SettingsItem.java @@ -2,6 +2,13 @@ package org.dolphinemu.dolphinemu.model.settings.view; 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,41 +22,73 @@ 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() @@ -57,5 +96,11 @@ public abstract class SettingsItem 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(); } diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SingleChoiceSetting.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SingleChoiceSetting.java index 12b7ae4882..07880587c2 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SingleChoiceSetting.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SingleChoiceSetting.java @@ -4,7 +4,7 @@ package org.dolphinemu.dolphinemu.model.settings.view; 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; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SliderSetting.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SliderSetting.java index 062f5f3cdc..0dbb39b521 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SliderSetting.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SliderSetting.java @@ -6,7 +6,7 @@ import org.dolphinemu.dolphinemu.model.settings.Setting; 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; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SubmenuSetting.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SubmenuSetting.java index 1e15555cda..32db709b37 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SubmenuSetting.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/model/settings/view/SubmenuSetting.java @@ -2,7 +2,7 @@ package org.dolphinemu.dolphinemu.model.settings.view; import org.dolphinemu.dolphinemu.model.settings.Setting; -public class SubmenuSetting extends SettingsItem +public final class SubmenuSetting extends SettingsItem { private String mMenuKey; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/DividerItemDecoration.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/DividerItemDecoration.java index 96b569e060..fcd0befdc2 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/DividerItemDecoration.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/DividerItemDecoration.java @@ -14,7 +14,7 @@ import android.view.View; * Implementation from: * https://gist.github.com/lapastillaroja/858caf1a82791b6c1a36 */ -public class DividerItemDecoration extends RecyclerView.ItemDecoration +public final class DividerItemDecoration extends RecyclerView.ItemDecoration { private Drawable mDivider; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityPresenter.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityPresenter.java index 07f58024b8..aac7e8e2ed 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityPresenter.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityPresenter.java @@ -13,7 +13,7 @@ import rx.android.schedulers.AndroidSchedulers; import rx.functions.Action1; import rx.schedulers.Schedulers; -public class SettingsActivityPresenter +public final class SettingsActivityPresenter { private SettingsActivityView mView; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityView.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityView.java index 4299335684..2409ed1221 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityView.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsActivityView.java @@ -4,15 +4,48 @@ import org.dolphinemu.dolphinemu.model.settings.SettingSection; 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 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 settings); + /** + * Called when an asynchronous load operation completes. + * + * @param settings The (possibly null) result of the load operation. + */ void onSettingsFileLoaded(HashMap settings); + /** + * Display a popup text message on screen. + * + * @param message The contents of the onscreen message. + */ void showToastMessage(String message); } diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsAdapter.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsAdapter.java index bbb9a2ad1a..ca754bb882 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsAdapter.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsAdapter.java @@ -30,7 +30,7 @@ import org.dolphinemu.dolphinemu.utils.SettingsFile; import java.util.ArrayList; -public class SettingsAdapter extends RecyclerView.Adapter +public final class SettingsAdapter extends RecyclerView.Adapter implements DialogInterface.OnClickListener, SeekBar.OnSeekBarChangeListener { private SettingsFragmentView mView; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentPresenter.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentPresenter.java index 22bb24a38f..6cb03472c0 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentPresenter.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentPresenter.java @@ -17,7 +17,7 @@ import org.dolphinemu.dolphinemu.utils.SettingsFile; import java.util.ArrayList; import java.util.HashMap; -public class SettingsFragmentPresenter +public final class SettingsFragmentPresenter { private SettingsFragmentView mView; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentView.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentView.java index f5a035eed3..0c0546d490 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentView.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/SettingsFragmentView.java @@ -9,19 +9,61 @@ import org.dolphinemu.dolphinemu.model.settings.view.SettingsItem; 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 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 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 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); } diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/CheckboxSettingViewHolder.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/CheckBoxSettingViewHolder.java similarity index 95% rename from Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/CheckboxSettingViewHolder.java rename to Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/CheckBoxSettingViewHolder.java index 05985cc671..c65fde1d66 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/CheckboxSettingViewHolder.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/CheckBoxSettingViewHolder.java @@ -10,7 +10,7 @@ import org.dolphinemu.dolphinemu.model.settings.view.CheckBoxSetting; import org.dolphinemu.dolphinemu.model.settings.view.SettingsItem; import org.dolphinemu.dolphinemu.ui.settings.SettingsAdapter; -public class CheckBoxSettingViewHolder extends SettingViewHolder +public final class CheckBoxSettingViewHolder extends SettingViewHolder { private CheckBoxSetting mItem; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/HeaderViewHolder.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/HeaderViewHolder.java index 9f0ba58196..6e3b53d4b3 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/HeaderViewHolder.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/HeaderViewHolder.java @@ -7,7 +7,7 @@ import org.dolphinemu.dolphinemu.R; import org.dolphinemu.dolphinemu.model.settings.view.SettingsItem; import org.dolphinemu.dolphinemu.ui.settings.SettingsAdapter; -public class HeaderViewHolder extends SettingViewHolder +public final class HeaderViewHolder extends SettingViewHolder { private TextView mHeaderName; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SettingViewHolder.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SettingViewHolder.java index ffa7d59d81..f57e9fc82c 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SettingViewHolder.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SettingViewHolder.java @@ -26,9 +26,26 @@ public abstract class SettingViewHolder extends RecyclerView.ViewHolder implemen return mAdapter; } + /** + * Gets handles to all this ViewHolder's child views using their XML-defined identifiers. + * + * @param root The newly inflated top-level view. + */ protected abstract void findViews(View root); + /** + * Called by the adapter to set this ViewHolder's child views to display the list item + * it must now represent. + * + * @param item The list item that should be represented by this ViewHolder. + */ public abstract void bind(SettingsItem item); + /** + * Called when this ViewHolder's view is clicked on. Implementations should usually pass + * this event up to the adapter. + * + * @param clicked The view that was clicked on. + */ public abstract void onClick(View clicked); } diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SingleChoiceViewHolder.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SingleChoiceViewHolder.java index a9230d2ee4..add1b76637 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SingleChoiceViewHolder.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SingleChoiceViewHolder.java @@ -8,7 +8,7 @@ import org.dolphinemu.dolphinemu.model.settings.view.SettingsItem; import org.dolphinemu.dolphinemu.model.settings.view.SingleChoiceSetting; import org.dolphinemu.dolphinemu.ui.settings.SettingsAdapter; -public class SingleChoiceViewHolder extends SettingViewHolder +public final class SingleChoiceViewHolder extends SettingViewHolder { private SingleChoiceSetting mItem; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SliderViewHolder.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SliderViewHolder.java index c15ddfaff6..9615c720fb 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SliderViewHolder.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SliderViewHolder.java @@ -9,7 +9,7 @@ import org.dolphinemu.dolphinemu.model.settings.view.SettingsItem; import org.dolphinemu.dolphinemu.model.settings.view.SliderSetting; import org.dolphinemu.dolphinemu.ui.settings.SettingsAdapter; -public class SliderViewHolder extends SettingViewHolder +public final class SliderViewHolder extends SettingViewHolder { private SliderSetting mItem; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SubmenuViewHolder.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SubmenuViewHolder.java index b90f1459a2..4a8243cec7 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SubmenuViewHolder.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/ui/settings/viewholder/SubmenuViewHolder.java @@ -8,7 +8,7 @@ import org.dolphinemu.dolphinemu.model.settings.view.SettingsItem; import org.dolphinemu.dolphinemu.model.settings.view.SubmenuSetting; import org.dolphinemu.dolphinemu.ui.settings.SettingsAdapter; -public class SubmenuViewHolder extends SettingViewHolder +public final class SubmenuViewHolder extends SettingViewHolder { private SubmenuSetting mItem; diff --git a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/utils/SettingsFile.java b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/utils/SettingsFile.java index 5bfa678098..7f9eb74742 100644 --- a/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/utils/SettingsFile.java +++ b/Source/Android/app/src/main/java/org/dolphinemu/dolphinemu/utils/SettingsFile.java @@ -23,6 +23,9 @@ import java.util.Set; import rx.Observable; import rx.Subscriber; +/** + * Contains static methods for interacting with .ini files in which settings are stored. + */ public final class SettingsFile { public static final String FILE_NAME_DOLPHIN = "Dolphin"; @@ -77,6 +80,14 @@ public final class SettingsFile { } + /** + * Reads a given .ini file from disk and returns it as an Rx Observable. If successful, + * this Observable emits a Hashmap of SettingSections, themselves effectively a Hashmap of + * key/value settings. If unsuccessful, the observer notifies the subscriber of why it failed. + * + * @param fileName The name of the settings file without a path or extension. + * @return An Observable that emits a Hashmap of the file's contents, then completes. + */ public static Observable> readFile(final String fileName) { return Observable.create(new Observable.OnSubscribe>() @@ -141,6 +152,15 @@ public final class SettingsFile }); } + /** + * Saves a Settings Hashmap to a given .ini file on disk, returning the operation + * as an Rx Observable. If successful, this Observable emits an event to notify subscribers; + * if unsuccessful, the observer notifies the subscriber of why it failed. + * + * @param fileName The target filename without a path or extension. + * @param sections The hashmap containing the Settings we want to serialize. + * @return An Observable representing the operation. + */ public static Observable saveFile(final String fileName, final HashMap sections) { return Observable.create(new Observable.OnSubscribe() @@ -199,6 +219,14 @@ public final class SettingsFile return new SettingSection(sectionName); } + /** + * For a line of text, determines what type of data is being represented, and returns + * a Setting object containing this data. + * + * @param current The section currently being parsed by the consuming method. + * @param line The line of text being parsed. + * @return A typed Setting containing the key/value contained in the line. + */ private static Setting settingFromLine(SettingSection current, String line) { String[] splitLine = line.split("="); @@ -237,6 +265,12 @@ public final class SettingsFile } } + /** + * Writes the contents of a Section hashmap to disk. + * + * @param writer A PrintWriter pointed at a file on disk. + * @param section A section containing settings to be written to the file. + */ private static void writeSection(PrintWriter writer, SettingSection section) { // Write the section header.