Add documentation and fix formating (#4860)

This commit is contained in:
Drashna Jaelre 2019-01-17 09:04:35 -08:00 committed by MechMerlin
parent f97894d8db
commit 5fcca9a226

View file

@ -17,7 +17,7 @@ uint32_t default_layer_state = 0;
/** \brief Default Layer State Set At user Level
*
* FIXME: Needs docs
* Run user code on default layer state change
*/
__attribute__((weak))
uint32_t default_layer_state_set_user(uint32_t state) {
@ -26,7 +26,7 @@ uint32_t default_layer_state_set_user(uint32_t state) {
/** \brief Default Layer State Set At Keyboard Level
*
* FIXME: Needs docs
* Run keyboard code on default layer state change
*/
__attribute__((weak))
uint32_t default_layer_state_set_kb(uint32_t state) {
@ -35,10 +35,9 @@ uint32_t default_layer_state_set_kb(uint32_t state) {
/** \brief Default Layer State Set
*
* FIXME: Needs docs
* Static function to set the default layer state, prints debug info and clears keys
*/
static void default_layer_state_set(uint32_t state)
{
static void default_layer_state_set(uint32_t state) {
state = default_layer_state_set_kb(state);
debug("default_layer_state: ");
default_layer_debug(); debug(" to ");
@ -53,45 +52,40 @@ static void default_layer_state_set(uint32_t state)
/** \brief Default Layer Print
*
* FIXME: Needs docs
* Print out the hex value of the 32-bit default layer state, as well as the value of the highest bit.
*/
void default_layer_debug(void)
{
void default_layer_debug(void) {
dprintf("%08lX(%u)", default_layer_state, biton32(default_layer_state));
}
/** \brief Default Layer Set
*
* FIXME: Needs docs
* Sets the default layer state.
*/
void default_layer_set(uint32_t state)
{
void default_layer_set(uint32_t state) {
default_layer_state_set(state);
}
#ifndef NO_ACTION_LAYER
/** \brief Default Layer Or
*
* FIXME: Needs docs
* Turns on the default layer based on matching bits between specifed layer and existing layer state
*/
void default_layer_or(uint32_t state)
{
void default_layer_or(uint32_t state) {
default_layer_state_set(default_layer_state | state);
}
/** \brief Default Layer And
*
* FIXME: Needs docs
* Turns on default layer based on matching enabled bits between specifed layer and existing layer state
*/
void default_layer_and(uint32_t state)
{
void default_layer_and(uint32_t state) {
default_layer_state_set(default_layer_state & state);
}
/** \brief Default Layer Xor
*
* FIXME: Needs docs
* Turns on default layer based on non-matching bits between specifed layer and existing layer state
*/
void default_layer_xor(uint32_t state)
{
void default_layer_xor(uint32_t state) {
default_layer_state_set(default_layer_state ^ state);
}
#endif
@ -104,7 +98,7 @@ uint32_t layer_state = 0;
/** \brief Layer state set user
*
* FIXME: Needs docs
* Runs user code on layer state change
*/
__attribute__((weak))
uint32_t layer_state_set_user(uint32_t state) {
@ -113,7 +107,7 @@ uint32_t layer_state_set_user(uint32_t state) {
/** \brief Layer state set keyboard
*
* FIXME: Needs docs
* Runs keyboard code on layer state change
*/
__attribute__((weak))
uint32_t layer_state_set_kb(uint32_t state) {
@ -122,10 +116,9 @@ uint32_t layer_state_set_kb(uint32_t state) {
/** \brief Layer state set
*
* FIXME: Needs docs
* Sets the layer to match the specifed state (a bitmask)
*/
void layer_state_set(uint32_t state)
{
void layer_state_set(uint32_t state) {
state = layer_state_set_kb(state);
dprint("layer_state: ");
layer_debug(); dprint(" to ");
@ -140,25 +133,23 @@ void layer_state_set(uint32_t state)
/** \brief Layer clear
*
* Turn off all layers.
* Turn off all layers
*/
void layer_clear(void)
{
void layer_clear(void) {
layer_state_set(0);
}
/** \brief Layer state is
*
* Return whether the given state is on (it might still be shadowed by a higher state, though).
* Return whether the given state is on (it might still be shadowed by a higher state, though)
*/
bool layer_state_is(uint8_t layer)
{
bool layer_state_is(uint8_t layer) {
return layer_state_cmp(layer_state, layer);
}
/** \brief Layer state compare
*
* FIXME: Needs docs
* Used for comparing layers {mostly used for unit testing}
*/
bool layer_state_cmp(uint32_t cmp_layer_state, uint8_t layer) {
if (!cmp_layer_state) { return layer == 0; }
@ -167,62 +158,55 @@ bool layer_state_cmp(uint32_t cmp_layer_state, uint8_t layer) {
/** \brief Layer move
*
* Turn on the given layer and turn off all other layers.
* Turns on the given layer and turn off all other layers
*/
void layer_move(uint8_t layer)
{
void layer_move(uint8_t layer) {
layer_state_set(1UL<<layer);
}
/** \brief Layer on
*
* Turn on the given layer.
* Turns on given layer
*/
void layer_on(uint8_t layer)
{
void layer_on(uint8_t layer) {
layer_state_set(layer_state | (1UL<<layer));
}
/** \brief Layer off
*
* FIXME: Needs docs
* Turns off given layer
*/
void layer_off(uint8_t layer)
{
void layer_off(uint8_t layer) {
layer_state_set(layer_state & ~(1UL<<layer));
}
/** \brief Layer invert
*
* Toggle the given layer (set it if it's unset, or unset it if it's set).
* Toggle the given layer (set it if it's unset, or unset it if it's set)
*/
void layer_invert(uint8_t layer)
{
void layer_invert(uint8_t layer) {
layer_state_set(layer_state ^ (1UL<<layer));
}
/** \brief Layer or
*
* FIXME: Needs docs
* Turns on layers based on matching bits between specifed layer and existing layer state
*/
void layer_or(uint32_t state)
{
void layer_or(uint32_t state) {
layer_state_set(layer_state | state);
}
/** \brief Layer and
*
* FIXME: Needs docs
* Turns on layers based on matching enabled bits between specifed layer and existing layer state
*/
void layer_and(uint32_t state)
{
void layer_and(uint32_t state) {
layer_state_set(layer_state & state);
}
/** \brief Layer xor
*
* FIXME: Needs docs
* Turns on layers based on non-matching bits between specifed layer and existing layer state
*/
void layer_xor(uint32_t state)
{
void layer_xor(uint32_t state) {
layer_state_set(layer_state ^ state);
}
@ -230,17 +214,22 @@ void layer_xor(uint32_t state)
*
* Print out the hex value of the 32-bit layer state, as well as the value of the highest bit.
*/
void layer_debug(void)
{
void layer_debug(void) {
dprintf("%08lX(%u)", layer_state, biton32(layer_state));
}
#endif
#if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE)
/** \brief source layer cache
*/
uint8_t source_layers_cache[(MATRIX_ROWS * MATRIX_COLS + 7) / 8][MAX_LAYER_BITS] = {{0}};
void update_source_layers_cache(keypos_t key, uint8_t layer)
{
/** \brief update source layers cache
*
* Updates the cached keys when changing layers
*/
void update_source_layers_cache(keypos_t key, uint8_t layer) {
const uint8_t key_number = key.col + (key.row * MATRIX_COLS);
const uint8_t storage_row = key_number / 8;
const uint8_t storage_bit = key_number % 8;
@ -253,8 +242,11 @@ void update_source_layers_cache(keypos_t key, uint8_t layer)
}
}
uint8_t read_source_layers_cache(keypos_t key)
{
/** \brief read source layers cache
*
* reads the cached keys stored when the layer was changed
*/
uint8_t read_source_layers_cache(keypos_t key) {
const uint8_t key_number = key.col + (key.row * MATRIX_COLS);
const uint8_t storage_row = key_number / 8;
const uint8_t storage_bit = key_number % 8;
@ -278,8 +270,7 @@ uint8_t read_source_layers_cache(keypos_t key)
* when the layer is switched after the down event but before the up
* event as they may get stuck otherwise.
*/
action_t store_or_get_action(bool pressed, keypos_t key)
{
action_t store_or_get_action(bool pressed, keypos_t key) {
#if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE)
if (disable_action_cache) {
return layer_switch_get_action(key);
@ -303,10 +294,9 @@ action_t store_or_get_action(bool pressed, keypos_t key)
/** \brief Layer switch get layer
*
* FIXME: Needs docs
* Gets the layer based on key info
*/
int8_t layer_switch_get_layer(keypos_t key)
{
int8_t layer_switch_get_layer(keypos_t key) {
#ifndef NO_ACTION_LAYER
action_t action;
action.code = ACTION_TRANSPARENT;
@ -330,9 +320,8 @@ int8_t layer_switch_get_layer(keypos_t key)
/** \brief Layer switch get layer
*
* FIXME: Needs docs
* Gets action code based on key position
*/
action_t layer_switch_get_action(keypos_t key)
{
action_t layer_switch_get_action(keypos_t key) {
return action_for_key(layer_switch_get_layer(key), key);
}