From 35fda84ba830415a575b5f99f7405353ab8d3c93 Mon Sep 17 00:00:00 2001 From: kibigo! Date: Thu, 13 Jul 2017 03:26:08 -0700 Subject: [PATCH] Documentation pt. I --- .../glitch/actions/local_settings.js | 73 +++++++++++++++++ .../glitch/reducers/local_settings.js | 79 +++++++++++++++++++ app/javascript/glitch/util/bio_metadata.js | 30 +++++++ 3 files changed, 182 insertions(+) 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,