Elaborate and reformat doc comments

README.md

@@ -26,8 +26,8 @@ Who knew a keyboard could do so much?
   keys](https://getreuer.info/posts/keyboards/custom-shift-keys/index.html)
   – they're surprisingly tricky to get right; here is my approach
 
-* [Layer Lock key](layer-lock/index.html) – macro to stay in the current
-  layer
+* [Layer Lock key](https://getreuer.info/posts/keyboards/layer-lock/index.html)
+  – macro to stay in the current layer
 
 * [Mouse Turbo
   Click](https://getreuer.info/posts/keyboards/mouse-turbo-click/index.html)

features/achordion.c

@@ -11,10 +11,14 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
-//
-// For full documentation, see
-// https://getreuer.info/posts/keyboards/achordion
+
+/**
+ * @file achordion.c
+ * @brief Achordion implementation
+ *
+ * For full documentation, see
+ * <https://getreuer.info/posts/keyboards/achordion>
+ */
 
 #include "achordion.h"
 

features/achordion.h

@@ -11,38 +11,43 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
-//
-// Achordion: Customizing the tap-hold decision.
-//
-// This library customizes when tap-hold keys are considered held vs. tapped
-// based on the next pressed key, like Manna Harbour's Bilateral Combinations or
-// ZMK's positional hold. The library works on top of QMK's existing tap-hold
-// implementation. You define mod-tap and layer-tap keys as usual and use
-// Achordion to fine-tune the behavior.
-//
-// When QMK settles a tap-hold key as held, Achordion intercepts the event.
-// Achordion then revises the event as a tap or passes it along as a hold:
-//
-//  * Chord condition: On the next key press, a customizable `achordion_chord()`
-//    function is called, which takes the tap-hold key and the next key pressed
-//    as args. When the function returns true, the tap-hold key is settled as
-//    held, and otherwise as tapped.
-//
-//  * Timeout: If no other key press occurs within a timeout, the tap-hold key
-//    is settled as held. This is customizable with `achordion_timeout()`.
-//
-// Achordion only changes the behavior when QMK considered the key held. It
-// changes some would-be holds to taps, but no taps to holds.
-//
-// NOTE: Some QMK features handle events before the point where Achordion can
-// intercept them, particularly: Combos, Key Lock, and Dynamic Macros. It's
-// still possible to use these features and Achordion in your keymap, but beware
-// they might behave poorly when used simultaneously with tap-hold keys.
-//
-//
-// For full documentation, see
-// https://getreuer.info/posts/keyboards/achordion
+
+/**
+ * @file achordion.h
+ * @brief Achordion: Customizing the tap-hold decision.
+ *
+ * Overview
+ * --------
+ *
+ * This library customizes when tap-hold keys are considered held vs. tapped
+ * based on the next pressed key, like Manna Harbour's Bilateral Combinations or
+ * ZMK's positional hold. The library works on top of QMK's existing tap-hold
+ * implementation. You define mod-tap and layer-tap keys as usual and use
+ * Achordion to fine-tune the behavior.
+ *
+ * When QMK settles a tap-hold key as held, Achordion intercepts the event.
+ * Achordion then revises the event as a tap or passes it along as a hold:
+ *
+ *  * Chord condition: On the next key press, a customizable `achordion_chord()`
+ *    function is called, which takes the tap-hold key and the next key pressed
+ *    as args. When the function returns true, the tap-hold key is settled as
+ *    held, and otherwise as tapped.
+ *
+ *  * Timeout: If no other key press occurs within a timeout, the tap-hold key
+ *    is settled as held. This is customizable with `achordion_timeout()`.
+ *
+ * Achordion only changes the behavior when QMK considered the key held. It
+ * changes some would-be holds to taps, but no taps to holds.
+ *
+ * @note Some QMK features handle events before the point where Achordion can
+ * intercept them, particularly: Combos, Key Lock, and Dynamic Macros. It's
+ * still possible to use these features and Achordion in your keymap, but beware
+ * they might behave poorly when used simultaneously with tap-hold keys.
+ *
+ *
+ * For full documentation, see
+ * <https://getreuer.info/posts/keyboards/achordion>
+ */
 
 #pragma once
 
@@ -52,74 +57,114 @@
 extern "C" {
 #endif
 
-// Call this function from `process_record_user()` as
-//
-//   bool process_record_user(uint16_t keycode, keyrecord_t* record) {
-//     if (!process_achordion(keycode, record)) { return false; }
-//     // Your macros...
-//     return true;
-//   }
+/**
+ * Handler function for Achordion.
+ *
+ * Call this function from `process_record_user()` as
+ *
+ *     #include "features/achordion.h"
+ *
+ *     bool process_record_user(uint16_t keycode, keyrecord_t* record) {
+ *       if (!process_achordion(keycode, record)) { return false; }
+ *       // Your macros...
+ *       return true;
+ *     }
+ */
 bool process_achordion(uint16_t keycode, keyrecord_t* record);
 
-// Call this function from `matrix_scan_user()` as
-//
-//   void matrix_scan_user(void) {
-//     achordion_task();
-//   }
+/**
+ * Matrix task function for Achordion.
+ *
+ * Call this function from `matrix_scan_user()` as
+ *
+ *     void matrix_scan_user(void) {
+ *       achordion_task();
+ *     }
+ */
 void achordion_task(void);
 
-// (Optional) In your keymap.c, define the callback
-//
-//   bool achordion_chord(uint16_t tap_hold_keycode,
-//                        keyrecord_t* tap_hold_record,
-//                        uint16_t other_keycode,
-//                        keyrecord_t* other_record) {
-//      // Conditions...
-//   }
-//
-// This callback is called if while `tap_hold_keycode` is pressed,
-// `other_keycode` is pressed. Return true if the tap-hold key should be
-// considered held, or false to consider it tapped.
+/**
+ * Optional callback to customize which key chords are considered "held".
+ *
+ * In your keymap.c, define the callback
+ *
+ *     bool achordion_chord(uint16_t tap_hold_keycode,
+ *                          keyrecord_t* tap_hold_record,
+ *                          uint16_t other_keycode,
+ *                          keyrecord_t* other_record) {
+ *        // Conditions...
+ *     }
+ *
+ * This callback is called if while `tap_hold_keycode` is pressed,
+ * `other_keycode` is pressed. Return true if the tap-hold key should be
+ * considered held, or false to consider it tapped.
+ *
+ * @param tap_hold_keycode Keycode of the tap-hold key.
+ * @param tap_hold_record keyrecord_t from the tap-hold press event.
+ * @param other_keycode Keycode of the other key.
+ * @param other_record keyrecord_t from the other key's press event.
+ * @return True if the tap-hold key should be considered held.
+ */
 bool achordion_chord(uint16_t tap_hold_keycode,
                      keyrecord_t* tap_hold_record,
                      uint16_t other_keycode,
                      keyrecord_t* other_record);
 
-// (Optional) In your keymap.c, define the callback
-//
-//   uint16_t achordion_timeout(uint16_t tap_hold_keycode) {
-//     // ...
-//   }
-//
-// The callback determines Achordion's timeout duration for `tap_hold_keycode`
-// in units of milliseconds. The timeout be in the range 0 to 32767 ms (upper
-// bound is due to 16-bit timer limitations). Use a timeout of 0 to bypass
-// Achordion.
+/**
+ * Optional callback to define a timeout duration per keycode.
+ *
+ * In your keymap.c, define the callback
+ *
+ *     uint16_t achordion_timeout(uint16_t tap_hold_keycode) {
+ *       // ...
+ *     }
+ *
+ * The callback determines Achordion's timeout duration for `tap_hold_keycode`
+ * in units of milliseconds. The timeout be in the range 0 to 32767 ms (upper
+ * bound is due to 16-bit timer limitations). Use a timeout of 0 to bypass
+ * Achordion.
+ *
+ * @param tap_hold_keycode Keycode of the tap-hold key.
+ * @return Timeout duration in milliseconds in the range 0 to 32767.
+ */
 uint16_t achordion_timeout(uint16_t tap_hold_keycode);
 
-// (Optional) Callback defining which mods are "eagerly" applied while a mod-tap
-// key is still being settled. This is helpful to reduce delay particularly when
-// using mod-tap keys with an external mouse.
-//
-// Define this callback in your keymap.c. The default callback is
-//
-//   bool achordion_eager_mod(uint8_t mod) {
-//     switch (mod) {
-//       case MOD_LSFT:
-//       case MOD_RSFT:
-//       case MOD_LCTL:
-//       case MOD_RCTL:
-//         return true;  // Eagerly apply Shift and Ctrl mods.
-//
-//      default:
-//        return false;
-//     }
-//   }
-//
-// NOTE: `mod` should be compared with `MOD_` prefixed codes, not `KC_` codes.
+/**
+ * Optional callback defining which mods are "eagerly" applied.
+ *
+ * This callback defines  which mods are "eagerly" applied while a mod-tap
+ * key is still being settled. This is helpful to reduce delay particularly when
+ * using mod-tap keys with an external mouse.
+ *
+ * Define this callback in your keymap.c. The default callback is
+ *
+ *     bool achordion_eager_mod(uint8_t mod) {
+ *       switch (mod) {
+ *         case MOD_LSFT:
+ *         case MOD_RSFT:
+ *         case MOD_LCTL:
+ *         case MOD_RCTL:
+ *           return true;  // Eagerly apply Shift and Ctrl mods.
+ *
+ *        default:
+ *          return false;
+ *       }
+ *     }
+ *
+ * @note `mod` should be compared with `MOD_` prefixed codes, not `KC_` codes.
+ *
+ * @param mod Modifier `MOD_` code.
+ * @return True if the modifier should be eagerly applied.
+ */
 bool achordion_eager_mod(uint8_t mod);
 
-// Returns true if the args come from keys on opposite hands.
+/**
+ * Returns true if the args come from keys on opposite hands.
+ *
+ * @param tap_hold_record keyrecord_t from the tap-hold key's event.
+ * @param other_record keyrecord_t from the other key's event.
+ * @return True if the keys are on opposite hands.
+ */
 bool achordion_opposite_hands(const keyrecord_t* tap_hold_record,
                               const keyrecord_t* other_record);
 

features/autocorrection.c

@@ -11,10 +11,14 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
-//
-// For full documentation, see
-// https://getreuer.info/posts/keyboards/autocorrection
+
+/**
+ * @file autocorrection.c
+ * @brief Autocorrection implementation
+ *
+ * For full documentation, see
+ * <https://getreuer.info/posts/keyboards/autocorrection>
+ */
 
 #include "autocorrection.h"