Documentation pt. I

This commit is contained in:
kibigo! 2017-07-13 03:26:08 -07:00
parent 5770d461b2
commit 35fda84ba8
3 changed files with 182 additions and 0 deletions

View file

@ -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();

View file

@ -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:

View file

@ -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,