Documentation pt. I

3 files changed, 182 insertions, 0 deletions

diff --git a/app/javascript/glitch/actions/local_settings.js b/app/javascript/glitch/actions/local_settings.js
index 18e0c245c..479b5841d 100644
--- a/app/javascript/glitch/actions/local_settings.js
+++ b/app/javascript/glitch/actions/local_settings.js
@@ -1,5 +1,60 @@
+/*
+
+`actions/local_settings`
+========================
+
+>   For more information on the contents of this file, please contact:
+>
+>   - kibigo! [@kibi@glitch.social]
+
+This file provides our Redux actions related to local settings. It
+consists of the following:
+
+ -  __`changesLocalSetting(key, value)` :__
+    Changes the local setting with the given `key` to the given
+    `value`. `key` **MUST** be an array of strings, as required by
+    `Immutable.Map.prototype.getIn()`.
+
+ -  __`saveLocalSettings()` :__
+    Saves the local settings to `localStorage` as a JSON object. We
+    shouldn't ever need to call this ourselves.
+
+*/
+
+                            /* * * * */
+
+/*
+
+Constants
+---------
+
+We provide the following constants:
+
+ -  __`LOCAL_SETTING_CHANGE` :__
+    This string constant is used to dispatch a setting change to our
+    reducer in `reducers/local_settings`, where the setting is
+    actually changed.
+
+*/
+
 export const LOCAL_SETTING_CHANGE = 'LOCAL_SETTING_CHANGE';
 
+                            /* * * * */
+
+/*
+
+`changeLocalSetting(key, value)`
+--------------------------------
+
+Changes the local setting with the given `key` to the given `value`.
+`key` **MUST** be an array of strings, as required by
+`Immutable.Map.prototype.getIn()`.
+
+To accomplish this, we just dispatch a `LOCAL_SETTING_CHANGE` to our
+reducer in `reducers/local_settings`.
+
+*/
+
 export function changeLocalSetting(key, value) {
   return dispatch => {
     dispatch({
@@ -12,6 +67,24 @@ export function changeLocalSetting(key, value) {
   };
 };
 
+                            /* * * * */
+
+/*
+
+`saveLocalSettings()`
+---------------------
+
+Saves the local settings to `localStorage` as a JSON object.
+`changeLocalSetting()` calls this whenever it changes a setting. We
+shouldn't ever need to call this ourselves.
+
+>   __TODO :__
+>   Right now `saveLocalSettings()` doesn't keep track of which user
+>   is currently signed in, but it might be better to give each user
+>   their *own* local settings.
+
+*/
+
 export function saveLocalSettings() {
   return (_, getState) => {
     const localSettings = getState().get('local_settings').toJS();
diff --git a/app/javascript/glitch/reducers/local_settings.js b/app/javascript/glitch/reducers/local_settings.js
index db99f2c46..79ff96307 100644
--- a/app/javascript/glitch/reducers/local_settings.js
+++ b/app/javascript/glitch/reducers/local_settings.js
@@ -1,3 +1,32 @@
+/*
+
+`reducers/local_settings`
+========================
+
+>   For more information on the contents of this file, please contact:
+>
+>   - kibigo! [@kibi@glitch.social]
+
+This file provides our Redux reducers related to local settings. The
+associated actions are:
+
+ -  __`STORE_HYDRATE` :__
+    Used to hydrate the store with its initial values.
+
+ -  __`LOCAL_SETTING_CHANGE` :__
+    Used to change the value of a local setting in the store.
+
+*/
+
+                            /* * * * */
+
+/*
+
+Imports
+-------
+
+*/
+
 //  Package imports  //
 import Immutable from 'immutable';
 
@@ -7,6 +36,18 @@ import { STORE_HYDRATE } from '../../mastodon/actions/store';
 //  Our imports  //
 import { LOCAL_SETTING_CHANGE } from '../actions/local_settings';
 
+                            /* * * * */
+
+/*
+
+initialState
+------------
+
+You can see the default values for all of our local settings here.
+These are only used if no previously-saved values exist.
+
+*/
+
 const initialState = Immutable.fromJS({
   layout    : 'auto',
   stretch   : true,
@@ -30,8 +71,46 @@ const initialState = Immutable.fromJS({
   },
 });
 
+                            /* * * * */
+
+/*
+
+Helper functions
+----------------
+
+###  `hydrate(state, localSettings)`
+
+`hydrate()` is used to hydrate the `local_settings` part of our store
+with its initial values. The `state` will probably just be the
+`initialState`, and the `localSettings` should be whatever we pulled
+from `localStorage`.
+
+*/
+
 const hydrate = (state, localSettings) => state.mergeDeep(localSettings);
 
+                            /* * * * */
+
+/*
+
+`localSettings(state = initialState, action)`
+---------------------------------------------
+
+This function holds our actual reducer.
+
+If our action is `STORE_HYDRATE`, then we call `hydrate()` with the
+`local_settings` property of the provided `action.state`.
+
+If our action is `LOCAL_SETTING_CHANGE`, then we set `action.key` in
+our state to the provided `action.value`. Note that `action.key` MUST
+be an array, since we use `setIn()`.
+
+>   __Note :__
+>   We call this function `localSettings`, but its associated object
+>   in the store is `local_settings`.
+
+*/
+
 export default function localSettings(state = initialState, action) {
   switch(action.type) {
   case STORE_HYDRATE:
diff --git a/app/javascript/glitch/util/bio_metadata.js b/app/javascript/glitch/util/bio_metadata.js
index bdbb1750b..c5e87f356 100644
--- a/app/javascript/glitch/util/bio_metadata.js
+++ b/app/javascript/glitch/util/bio_metadata.js
@@ -1,3 +1,33 @@
+/*
+
+`util/bio_metadata`
+========================
+
+>   For more information on the contents of this file, please contact:
+>
+>   - kibigo! [@kibi@glitch.social]
+
+This file provides two functions for dealing with bio metadata. The
+functions are:
+
+ -  __`processBio(content)` :__
+    Processes `content` to extract any frontmatter. The returned
+    object has two properties: `text`, which contains the text of
+    `content` sans-frontmatter, and `metadata`, which is an array
+    of key-value pairs (in two-element array format). If no
+    frontmatter was provided in `content`, then `metadata` will be
+    an empty array.
+
+ -  __`createBio(note, data)` :__
+    Reverses the process in `processBio()`; takes a `note` and an
+    array of two-element arrays (which should give keys and values)
+    and outputs a string containing a well-formed bio with
+    frontmatter.
+
+*/
+
+                            /* * * * */
+
 /*********************************************************************\
 
                                        To my lovely code maintainers,