Qmk_firmware: Document the QMK API and Internals

[skullydazed]

We want to document the QMK API and Internals to make it easier for people to write custom code and understand how QMK works. This is a pretty big project that will make it easier for people to use QMK, and will give you an opportunity to learn more about how QMK works yourself.

We're looking for help from the community to add documentation comments to all of the functions, defines, and other useful bits in quantum/ and tmk_core/.

How Can I Help?

Glad you asked! :D You can help by going through the list below and submitting PR's for the files inside. Most of the time you will only need to comment .c files, but sometimes you will need to comment includes (.h) as well.

What Should Be Commented?

Knowing what things in the source code to document is always a tricky call. In general, the following things should always be commented:

• Functions people will use in their keymaps
• #defines that can be put into config.h to control behavior
• Functions that QMK calls to get things done which are helpful for understanding QMK, e.g. process_record().

For everything else use your best judgement. When in doubt include a comment, we can always prune it later if it's not useful.

Comment Template

You can add documentation comments to any code structure that doxygen supports. Mostly you'll add them for functions and defines. A well structured documentation comment contains a short summary, called a brief, followed by a longer description. Your brief should be no longer than 60 characters.

This is an example of a documentation comment:

/** \brief A short description of this function/define/enum
  *
  * A longer description of this function/define/enum, with details about what parameters it expects and what its return value will be.
  * 
  * You can use **Markdown** code inside comments to _stylize_ them.
  */

Code directories

This is a list of directories that have not yet had documentation comments added or completed.

• [ ] tmk_core/protocol/bluefruit
• [ ] tmk_core/protocol/chibios
• [ ] tmk_core/protocol/iwrap
• [ ] tmk_core/protocol/lufa
• [ ] tmk_core/protocol/mbed
• [ ] tmk_core/protocol/midi/bytequeue
• [ ] tmk_core/protocol/midi/Config
• [ ] tmk_core/protocol/midi
• [ ] tmk_core/protocol/pjrc
• [ ] tmk_core/protocol/usb_hid
• [ ] tmk_core/protocol/vusb
• [ ] tmk_core/protocol
• [ ] tmk_core/tool/chibios
• [ ] tmk_core/tool
• [ ] quantum/api
• [ ] quantum/audio
• [ ] quantum/keymap_extras
• [ ] quantum/process_keycode
• [ ] quantum/serial_link/protocol
• [ ] quantum/serial_link/system
• [ ] quantum/serial_link/tests
• [ ] quantum/serial_link
• [ ] quantum/tools
• [ ] quantum/visualizer/resources
• [ ] quantum/visualizer
• [ ] quantum
• [ ] drivers/avr
• [ ] drivers/ugfx/gdisp
• [ ] drivers/ugfx/gdisp/is31fl3731c
• [ ] drivers/ugfx/gdisp/st7565
• [ ] drivers/ugfx
• [ ] drivers

[drashna]

Do we have some samples of where this has been done (and how it shows up)?

[skullydazed]

Both good questions!

I've added some placeholder comments to some of the files, for example here in tmk_core/protocol/lufa/lufa.c: https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L144

The files that currently get generated are in docs/api_*.md. We still need to do some work to get all of the docstrings pulled into these docs it looks like, but that will be the final location for those.

[ai212983]

Sorry guys for asking it here, but I've tried search and google for a two days by now with no avail.

I need to control keyboard backlight from a script, without actually touching a keyboard.

Can please someone point me to proper way to send messages/commands from computer to my keyboard and the way to handle it on keyboard side? Am I right that this is somehow implemented already, but lack documentation?

[drashna]

@ai212983 Not possible at the moment.
Jack is working on this, though: #2198

[ai212983]

@drashna: Ok, great, thanks a lot.

[stale[bot]]

This issue has been automatically marked as resolved because it has not had activity in the last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity occurs.