Adding Doxygen-style docs for IDE autocompletion in LinkPS2Mouse

README.md

@@ -396,7 +396,9 @@ The GBA operates using `1` stop bit, but everything else can be configured. By d
 
 # 🖱️ LinkPS2Mouse
 
-A PS/2 mouse driver for the GBA. Use it to add mouse support to your homebrew games.
+A PS/2 mouse driver for the GBA. Use it to add mouse support to your homebrew games. It's a straight port from [this library](https://github.com/kristopher/PS2-Mouse-Arduino).
+
+⚠️ calling `activate()` or `report(...)` could freeze the system if nothing is connected: detecting timeouts using timer interrupts is the user's responsibility.
 
 ![photo](https://github.com/afska/gba-link-connection/assets/1631752/6856ff0d-0f06-4a9d-8ded-280052e02b8d)
 
@@ -411,7 +413,7 @@ Name | Return type | Description
 `isActive()` | **bool** | Returns whether the library is active or not.
 `activate()` | - | Activates the library.
 `deactivate()` | - | Deactivates the library.
-`report(data[3])` | - | Fills the `data` int array with a report. The first int contains _clicks_ that you can check against the bitmasks `LINK_PS2_MOUSE_LEFT_CLICK`, `LINK_PS2_MOUSE_MIDDLE_CLICK`, and `LINK_PS2_MOUSE_RIGHT_CLICK`. The second int is the _X movement_, and the third int is the _Y movement_.
+`report(data[3])` | - | Fills the `data` int array with a report. The first int contains *clicks* that you can check against the bitmasks `LINK_PS2_MOUSE_LEFT_CLICK`, `LINK_PS2_MOUSE_MIDDLE_CLICK`, and `LINK_PS2_MOUSE_RIGHT_CLICK`. The second int is the *X movement*, and the third int is the *Y movement*.
 
 ## Pinout
 

examples/LinkPS2Mouse_demo/src/main.cpp

@@ -12,6 +12,10 @@ inline void TIMER() {}
 // (1) Create a LinkPS2Mouse instance
 LinkPS2Mouse* linkPS2Mouse = new LinkPS2Mouse(2);
 
+inline void KEYPAD() {
+  SoftReset();
+}
+
 void init() {
   REG_DISPCNT = DCNT_MODE0 | DCNT_BG0;
   tte_init_se_default(0, BG_CBB(0) | BG_SBB(31));
@@ -22,6 +26,11 @@ void init() {
   interrupt_enable(INTR_VBLANK);
   interrupt_set_handler(INTR_TIMER2, TIMER);
   interrupt_enable(INTR_TIMER2);
+
+  // Interrupt to handle B event (to reset)
+  REG_KEYCNT = 0b10 | (1 << 14);
+  interrupt_set_handler(INTR_KEYPAD, KEYPAD);
+  interrupt_enable(INTR_KEYPAD);
 }
 
 int main() {
@@ -32,7 +41,9 @@ int main() {
     u16 keys = ~REG_KEYS & KEY_ANY;
 
     if (!linkPS2Mouse->isActive()) {
-      output += "Press A to read mouse input";
+      output +=
+          "Press A to read mouse input\n"
+          "Press B to cancel";
 
       if (keys & KEY_A) {
         // (3) Initialize the library

lib/LinkGPIO.hpp

@@ -81,7 +81,6 @@ class LinkGPIO {
 
   /**
    * @brief Sets a `pin` to be high or not (when set as an output).
-   *
    * @param pin One of the enum values from `LinkGPIO::Pin`.
    * @param isHigh `true` = HIGH, `false` = LOW.
    */

lib/LinkPS2Keyboard.hpp

@@ -63,7 +63,6 @@ class LinkPS2Keyboard {
 
   /**
    * @brief Constructs a new LinkPS2Keyboard object.
-   *
    * @param onEvent Function pointer that will receive the scan codes (`u8`).
    * Check out `LINK_PS2_KEYBOARD_KEY` and `LINK_PS2_KEYBOARD_EVENT` for codes.
    */

lib/LinkPS2Mouse.hpp

@@ -21,6 +21,10 @@
 //       data[1] // X movement
 //       data[2] // Y movement
 // --------------------------------------------------------------------------
+// considerations:
+// - `activate()` or `report(...)` could freeze the system if not connected!
+// - detecting timeouts using timer interrupts is the user's responsibility!
+// --------------------------------------------------------------------------
 //  ____________
 // |   Pinout   |
 // |PS/2 --- GBA|
@@ -39,6 +43,9 @@ static volatile char LINK_PS2_MOUSE_VERSION[] = "LinkPS2Mouse/v7.0.0";
 #define LINK_PS2_MOUSE_RIGHT_CLICK 0b010
 #define LINK_PS2_MOUSE_MIDDLE_CLICK 0b100
 
+/**
+ * @brief A PS/2 Mouse Adapter for the GBA.
+ */
 class LinkPS2Mouse {
  private:
   using u32 = unsigned int;
@@ -54,10 +61,22 @@ class LinkPS2Mouse {
   static constexpr int TO_TICKS = 17;
 
  public:
+  /**
+   * @brief Constructs a new LinkPS2Mouse object.
+   * @param waitTimerId `(0~3)` GBA Timer used for delays.
+   */
   explicit LinkPS2Mouse(u8 waitTimerId) { this->waitTimerId = waitTimerId; }
 
+  /**
+   * @brief Returns whether the library is active or not.
+   */
   [[nodiscard]] bool isActive() { return isEnabled; }
 
+  /**
+   * @brief Activates the library.
+   * \warning Could freeze the system if nothing is connected!
+   * \warning Detect timeouts using timer interrupts!
+   */
   void activate() {
     deactivate();
 
@@ -76,6 +95,9 @@ class LinkPS2Mouse {
     isEnabled = true;
   }
 
+  /**
+   * @brief Deactivates the library.
+   */
   void deactivate() {
     isEnabled = false;
 
@@ -83,6 +105,14 @@ class LinkPS2Mouse {
     Link::_REG_SIOCNT = 0;
   }
 
+  /**
+   * @brief Fills the `data` int array with a report. The first int contains
+   * *clicks* that you can check against the bitmasks
+   * `LINK_PS2_MOUSE_LEFT_CLICK`, `LINK_PS2_MOUSE_MIDDLE_CLICK`, and
+   * `LINK_PS2_MOUSE_RIGHT_CLICK`. The second int is the *X movement*, and the
+   * third int is the *Y movement*.
+   * @param data The array to be filled with data.
+   */
   void report(int (&data)[3]) {
     write(0xeb);                       // send read data
     readByte();                        // read ack byte

lib/LinkSPI.hpp

@@ -101,7 +101,6 @@ class LinkSPI {
 
   /**
    * @brief Activates the library in a specific `mode`.
-   *
    * @param mode One of `LinkSPI::Mode::SLAVE`, `LinkSPI::Mode::MASTER_256KBPS`,
    * or `LinkSPI::Mode::MASTER_2MBPS`.
    */