Qmk_firmware: Documentation for layer switching is confusing

[henrebotha]

I am reading the docs, trying to get a grip on how layer switching works. But the docs are very lacking in explaining how layers (a core concept) work, using vague and inconsistent wording.

other codes only let you go up the stack (from layer 0 to layer 3, for example)

Okay, so "up" means "increasing layer number". Got it.

Never try to stack a higher numbered layer on top of a lower numbered layer. Doing so is tricky and error prone.

Wait, what? So we _shouldn't_ put higher numbers on top of lower numbers? Or does "on top of" actually mean "underneath"?

Layers stack on top of each other in numerical order.

Which numerical order? If the stack goes (from top to bottom) 3, 2, 1, 0, then that's reverse numerical order, isn't it?

---

Minor additional gripe:

For Modifier keys and layer actions you have to place KC_TRANS on same position of destination layer to unregister the modifier key or return to previous layer on release event.

I have to check the FAQ for this. Why isn't it specified in the actual layers section of the docs?

[skullydazed]

Organizing and presenting this information coherently is something we've been working on. Sorry it's been confusing for you. Until I have a chance to revisit this topic and work on that documentation again maybe I can help clarify for you.

Wait, what? So we shouldn't put higher numbers on top of lower numbers? Or does "on top of" actually mean "underneath"?

What we're trying to convey here is that you shouldn't try to activate a layer that is numerically lower (unless you know how it operates and can avoid certain pitfalls.) For example, don't put MO(3) on layer 4. The reason is that it's not only possible but actually very easy to lock a layer on with no way to deactivate it. The advanced section explains why, but we've found that understanding the advanced section requires several layers of understanding (no pun intended.)

Which numerical order? If the stack goes (from top to bottom) 3, 2, 1, 0, then that's reverse numerical order, isn't it?

From an implementation standpoint layers are simply an array of arrays. The inner array is the keymap, the outer array are the layers. When a keyup/down event happens QMK checks the active layers for a key that is not KC_TRNS, starting with the highest numbered active layer and moving down until it eventually encounters a key that is not KC_TRNS.

I have to check the FAQ for this. Why isn't it specified in the actual layers section of the docs?

A good question. :) I think we try to convey that but it's rather indirect. That will be something to keep in mind when we rework this.

[thriondil]

I was also quite confused by this line:

Never try to stack a higher numbered layer on top of a lower numbered layer. Doing so is tricky and error prone.

Adding just this comment to the same section would help immensely:

For example, don't put MO(3) on layer 4.

As a newer user, it was not at all clear what "stack on" means

[homocomputeris]

It is described somewhat better here.
The least explained thing still is why stacking if direct unconditional TO switching exists.

[jackhumbert]

I know we've rewritten the docs a couple of times since this, and I hope we've addressed it. If there was something confusing that's still there, please let us know and we can make adjustments to that specific section.