-
-
Notifications
You must be signed in to change notification settings - Fork 37.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document how QMK_KEYBOARD_H
works and what files it includes
#23722
Comments
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? |
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. |
I know it's tucked away, but it is documented: 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. |
I saw that, which is why I wrote this:
|
Issue Description
As I noted in #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 includingquantum.h
and defining some keyboard-specific data, such asMATRIX_ROWS
andMATRIX_COLS
?The text was updated successfully, but these errors were encountered: