search

qmk / qmk_firmware

Open-source keyboard firmware for Atmel AVR and Arm USB families
https://qmk.fm
GNU General Public License v2.0
17.76k stars 38k forks source link

Document how `QMK_KEYBOARD_H` works and what files it includes #23722

Open NoahAndrews opened 2 months ago

NoahAndrews commented 2 months ago

Issue Description

As I noted in https://github.com/qmk/qmk_firmware/issues/23721, my perspective is that of someone who used to be a QMK almost-expert, but whose knowledge is now mostly 7 years stale.

As far as I can tell, QMK_KEYBOARD_H is pretty much undocumented black magic. I imagine it was somewhat simpler before the data-driven config system (if it existed back then), but now that most (all?) keyboards don't even have a <keyboard>.h file, it's extremely unclear to C-knowledgeable newcomers what's actually being included into their keymap file, at least if they don't have a proper C-aware IDE set up.

I suspect that the top-level list of things that are imported is actually pretty short (most of the complexity of what gets included looks to still live in quantum.h), so I suspect this isn't a huge task. Is it as simple as including quantum.h and defining some keyboard-specific data, such as MATRIX_ROWS and MATRIX_COLS?

tzarc commented 2 months ago

I'll be honest, since it came into existence you're the only person I know of that has asked "what else does this actually include?"

To me, that's a sign that it's not a good candidate to sink a lot of time into documenting its purpose, as people in general don't seem to care. What exactly do you want to achieve with this line of inquiry?

NoahAndrews commented 2 months ago

I'm of the opinion that while magic is great, a user-facing API should be clearly documented. Right now, there's no documentation about what macros and identifiers are being imported into the file's namespace, which is very basic information. While I love that the system has gotten much more user-friendly, at the end of the day keymaps are still fully-fledged C files, and developer end-users deserve to be able to know what's in their keymap file.

There's a decent chance I'll end up PRing this myself, once I understand the system better.

drashna commented 2 months ago

I know it's tucked away, but it is documented: https://docs.qmk.fm/#/feature_layouts?id=tips-for-making-layouts-keyboard-agnostic

Honestly, the docs could use a lot of work, and I think the biggest issue that we're looking at right now is searchability. And from there, I think there has been talk about splitting consumer and designer/manufacturer content.

NoahAndrews commented 2 months ago

I know it's tucked away, but it is documented: https://docs.qmk.fm/#/feature_layouts?id=tips-for-making-layouts-keyboard-agnostic

I saw that, which is why I wrote this:

I imagine it was somewhat simpler before the data-driven config system (if it existed back then), but now that most (all?) keyboards don't even have a .h file, it's extremely unclear to C-knowledgeable newcomers what's actually being included into their keymap file