Lift Joybus + Joypad documentation into headers

src/joybus_accessory.c

@@ -14,16 +14,6 @@
  * @{
  */
 
-/**
- * @brief Applies the checksum to a Joybus N64 accessory read/write address.
- * 
- * When reading or writing a particular address on the accessory, the command
- * will send the top 11 bits of a 16 bit address, plus a 5 bit checksum.
- * 
- * @param addr The address to calculate the checksum for.
- * 
- * @return The address with the checksum applied.
- */
 uint16_t joybus_accessory_calculate_addr_checksum(uint16_t addr)
 {
     static const uint16_t xor_table[16] = {
@@ -45,17 +35,6 @@ uint16_t joybus_accessory_calculate_addr_checksum(uint16_t addr)
     return addr | checksum;
 }
 
-/**
- * @brief Calculates the CRC8 checksum for a Joybus N64 accessory read/write data block.
- * 
- * Uses a CRC8 algorithm with a seed of 0x00 and a polynomial of 0x85.
- * 
- * This implementation has been tuned for optimal performance.
- * 
- * @param[in] data The 32-byte accessory read/write data block
- * 
- * @return The calculated CRC8 checksum for the data block 
- */
 uint8_t joybus_accessory_calculate_data_crc(const uint8_t *data)
 {
     unsigned int crc = 0;
@@ -77,17 +56,6 @@ uint8_t joybus_accessory_calculate_data_crc(const uint8_t *data)
     return crc;
 }
 
-/**
- * @brief Calculates the CRC8 checksum for an accessory read/write data block and
- * compares it against the provided checksum.
- * 
- * @param[in] data The 32-byte accessory read/write data block
- * @param data_crc The CRC8 checksum to compare against
- * 
- * @retval #JOYBUS_ACCESSORY_IO_STATUS_OK The checksums match.
- * @retval #JOYBUS_ACCESSORY_IO_STATUS_NO_PAK The checksum indicates that no accessory is present.
- * @retval #JOYBUS_ACCESSORY_IO_STATUS_BAD_CRC The data checksum does not match the provided checksum.
- */
 joybus_accessory_io_status_t joybus_accessory_compare_data_crc(
     const uint8_t *data,
     uint8_t data_crc
@@ -105,14 +73,6 @@ joybus_accessory_io_status_t joybus_accessory_compare_data_crc(
     return JOYBUS_ACCESSORY_IO_STATUS_BAD_CRC;
 }
 
-/**
- * @brief Asynchronously perform a Joybus N64 accessory read command.
- * 
- * @param port The controller port of the accessory to read from.
- * @param addr The accessory address to read from.
- * @param callback A function pointer to call when the operation completes.
- * @param ctx A user data pointer to pass into the callback function.
- */
 void joybus_accessory_read_async(
     int port,
     uint16_t addr,
@@ -140,15 +100,6 @@ void joybus_accessory_read_async(
     joybus_exec_async(input, callback, ctx);
 }
 
-/**
- * @brief Asynchronously perform a Joybus N64 accessory write command.
- * 
- * @param port The controller port of the accessory to write to.
- * @param addr The accessory address to write to.
- * @param[in] data The data to write to the accessory.
- * @param callback A function pointer to call when the operation completes.
- * @param ctx A user data pointer to pass into the callback function.
- */
 void joybus_accessory_write_async(
     int port,
     uint16_t addr,

src/joybus_accessory_internal.h

@@ -208,11 +208,61 @@ typedef union
     /// @endcond
 } joybus_transfer_pak_status_t;
 
+/**
+ * @brief Applies the checksum to a Joybus N64 accessory read/write address.
+ * 
+ * When reading or writing a particular address on the accessory, the command
+ * will send the top 11 bits of a 16 bit address, plus a 5 bit checksum.
+ * 
+ * @param addr The address to calculate the checksum for.
+ * 
+ * @return The address with the checksum applied.
+ */
 uint16_t joybus_accessory_calculate_addr_checksum(uint16_t addr);
+
+/**
+ * @brief Calculates the CRC8 checksum for a Joybus N64 accessory read/write data block.
+ * 
+ * Uses a CRC8 algorithm with a seed of 0x00 and a polynomial of 0x85.
+ * 
+ * @param[in] data The 32-byte accessory read/write data block
+ * 
+ * @return The calculated CRC8 checksum for the data block 
+ */
 uint8_t joybus_accessory_calculate_data_crc(const uint8_t *data);
+
+/**
+ * @brief Calculates the CRC8 checksum for an accessory read/write data block and
+ * compares it against the provided checksum.
+ * 
+ * @param[in] data The 32-byte accessory read/write data block
+ * @param data_crc The CRC8 checksum to compare against
+ * 
+ * @retval #JOYBUS_ACCESSORY_IO_STATUS_OK The checksums match.
+ * @retval #JOYBUS_ACCESSORY_IO_STATUS_NO_PAK The checksum indicates that no accessory is present.
+ * @retval #JOYBUS_ACCESSORY_IO_STATUS_BAD_CRC The data checksum does not match the provided checksum.
+ */
 joybus_accessory_io_status_t joybus_accessory_compare_data_crc(const uint8_t *data, uint8_t data_crc);
 
+/**
+ * @brief Asynchronously perform a Joybus N64 accessory read command.
+ * 
+ * @param port The controller port of the accessory to read from.
+ * @param addr The accessory address to read from.
+ * @param callback A function pointer to call when the operation completes.
+ * @param ctx A user data pointer to pass into the callback function.
+ */
 void joybus_accessory_read_async(int port, uint16_t addr, joybus_callback_t callback, void *ctx);
+
+/**
+ * @brief Asynchronously perform a Joybus N64 accessory write command.
+ * 
+ * @param port The controller port of the accessory to write to.
+ * @param addr The accessory address to write to.
+ * @param[in] data The data to write to the accessory.
+ * @param callback A function pointer to call when the operation completes.
+ * @param ctx A user data pointer to pass into the callback function.
+ */
 void joybus_accessory_write_async(int port, uint16_t addr, const uint8_t *data, joybus_callback_t callback, void *ctx);
 
 #ifdef __cplusplus

src/joypad.c

@@ -737,7 +737,7 @@ int joypad_get_accessory_error(joypad_port_t port)
     return joypad_accessories_hot[port].error;
 }
 
-uint8_t joypad_get_accessory_transfer_pak_status(joypad_port_t port)
+uint8_t joypad_get_transfer_pak_status(joypad_port_t port)
 {
     ASSERT_JOYPAD_INITIALIZED();
     ASSERT_JOYPAD_PORT_VALID(port);

src/joypad_accessory.c

@@ -451,22 +451,6 @@ static void joypad_accessory_detect_write_callback(uint64_t *out_dwords, void *c
     }
 }
 
-/**
- * @brief Detect which accessory is inserted in an N64 controller.
- *
- * * Step 1: Ensure Transfer Pak is turned off
- * * Step 2A: Overwrite "label" area to detect Controller Pak
- * * Step 2B: Read back the "label" area to detect Controller Pak
- * * Step 3A: Write probe value to detect Rumble Pak
- * * Step 3B: Read probe value to detect Rumble Pak
- * * Step 4A: Write probe value to detect Transfer Pak
- * * Step 4B: Read probe value to detect Transfer Pak
- * * Step 4C: Write probe value to turn off Transfer Pak
- * * Step 5A: Write probe value to detect Snap Station
- * * Step 5B: Read probe value to detect Snap Station
- *
- * @param port Joypad port to detect the accessory on (#joypad_port_t)
- */
 void joypad_accessory_detect_async(joypad_port_t port)
 {
     ASSERT_JOYPAD_PORT_VALID(port);
@@ -518,12 +502,6 @@ static void joypad_rumble_pak_motor_write_callback(uint64_t *out_dwords, void *c
     }
 }
 
-/**
- * @brief Turn the Rumble Pak motor on or off for a Joypad port.
- * 
- * @param port Joypad port number (#joypad_port_t)
- * @param active Whether the motor should be on (true) or off (false)
- */
 void joypad_rumble_pak_toggle_async(joypad_port_t port, bool active)
 {
     volatile joypad_device_hot_t *device = &joypad_devices_hot[port];
@@ -619,12 +597,6 @@ static void joypad_transfer_pak_enable_write_callback(uint64_t *out_dwords, void
     }
 }
 
-/**
- * @brief Enable or disable the Transfer Pak for a Joypad port.
- * 
- * @param port Joypad port number (#joypad_port_t)
- * @param enabled Whether the Transfer Pak should be enabled (true) or disabled (false)
- */
 void joypad_transfer_pak_enable_async(joypad_port_t port, bool enabled)
 {
     ASSERT_JOYPAD_PORT_VALID(port);
@@ -785,14 +757,6 @@ static void joypad_transfer_pak_load_write_callback(uint64_t *out_dwords, void *
     }
 }
 
-/**
- * @brief Load data from the GB cartridge inserted in a Transfer Pak.
- * 
- * @param port Joypad port number (#joypad_port_t)
- * @param cart_addr Starting address in the GB cartridge to load from.
- * @param[out] dst Destination buffer to load cartridge data into. 
- * @param len Number of bytes to load (must be a multiple of 32).
- */
 void joypad_transfer_pak_load_async(joypad_port_t port, uint16_t cart_addr, void *dst, size_t len)
 {
     ASSERT_JOYPAD_PORT_VALID(port);
@@ -960,14 +924,6 @@ static void joypad_transfer_pak_store_write_callback(uint64_t *out_dwords, void
     }
 }
 
-/**
- * @brief Store data on the GB cartridge inserted in a Transfer Pak.
- * 
- * @param port Joypad port number (#joypad_port_t)
- * @param cart_addr Starting address in the GB cartridge to store into.
- * @param[in] src Source buffer of data to store on GB cartridge. 
- * @param len Number of bytes to store (must be a multiple of 32).
- */
 void joypad_transfer_pak_store_async(joypad_port_t port, uint16_t cart_addr, void *src, size_t len)
 {
     ASSERT_JOYPAD_PORT_VALID(port);

src/joypad_accessory.h

@@ -115,15 +115,67 @@ typedef struct joypad_accessory_s
     joypad_transfer_pak_io_t transfer_pak_io;
 } joypad_accessory_t;
 
-joypad_accessory_type_t joypad_get_accessory_type(joypad_port_t port);
-int joypad_get_accessory_state(joypad_port_t port);
-int joypad_get_accessory_error(joypad_port_t port);
-uint8_t joypad_get_accessory_transfer_pak_status(joypad_port_t port);
-
+/**
+ * @brief Detect which accessory is inserted in an N64 controller.
+ *
+ * * Step 1: Ensure Transfer Pak is turned off
+ * * Step 2A: Overwrite "label" area to detect Controller Pak
+ * * Step 2B: Read back the "label" area to detect Controller Pak
+ * * Step 3A: Write probe value to detect Rumble Pak
+ * * Step 3B: Read probe value to detect Rumble Pak
+ * * Step 4A: Write probe value to detect Transfer Pak
+ * * Step 4B: Read probe value to detect Transfer Pak
+ * * Step 4C: Write probe value to turn off Transfer Pak
+ * * Step 5A: Write probe value to detect Snap Station
+ * * Step 5B: Read probe value to detect Snap Station
+ *
+ * @param port Joypad port to detect the accessory on (#joypad_port_t)
+ */
 void joypad_accessory_detect_async(joypad_port_t port);
+
+/**
+ * @brief Turn the Rumble Pak motor on or off for a Joypad port.
+ * 
+ * @param port Joypad port number (#joypad_port_t)
+ * @param active Whether the motor should be on (true) or off (false)
+ */
 void joypad_rumble_pak_toggle_async(joypad_port_t port, bool active);
+
+/**
+ * @brief Get the Transfer Pak status byte for a Joypad port.
+ * 
+ * @param port Joypad port number (#joypad_port_t)
+ * 
+ * @return Transfer Pak status byte (#joybus_transfer_pak_status_t)
+ */
+uint8_t joypad_get_transfer_pak_status(joypad_port_t port);
+
+/**
+ * @brief Enable or disable the Transfer Pak for a Joypad port.
+ * 
+ * @param port Joypad port number (#joypad_port_t)
+ * @param enabled Whether the Transfer Pak should be enabled (true) or disabled (false)
+ */
 void joypad_transfer_pak_enable_async(joypad_port_t port, bool enabled);
+
+/**
+ * @brief Load data from the GB cartridge inserted in a Transfer Pak.
+ * 
+ * @param port Joypad port number (#joypad_port_t)
+ * @param cart_addr Starting address in the GB cartridge to load from.
+ * @param[out] dst Destination buffer to load cartridge data into. 
+ * @param len Number of bytes to load (must be a multiple of 32).
+ */
 void joypad_transfer_pak_load_async(joypad_port_t port, uint16_t cart_addr, void *dst, size_t len);
+
+/**
+ * @brief Store data on the GB cartridge inserted in a Transfer Pak.
+ * 
+ * @param port Joypad port number (#joypad_port_t)
+ * @param cart_addr Starting address in the GB cartridge to store into.
+ * @param[in] src Source buffer of data to store on GB cartridge. 
+ * @param len Number of bytes to store (must be a multiple of 32).
+ */
 void joypad_transfer_pak_store_async(joypad_port_t port, uint16_t cart_addr, void *src, size_t len);
 
 #ifdef __cplusplus

src/joypad_internal.h

@@ -125,15 +125,6 @@ int joypad_get_accessory_state(joypad_port_t port);
  */
 int joypad_get_accessory_error(joypad_port_t port);
 
-/**
- * @brief Get the Transfer Pak status byte for a Joypad port.
- * 
- * @param port Joypad port number (#joypad_port_t)
- * 
- * @return Transfer Pak status byte 
- */
-uint8_t joypad_get_accessory_transfer_pak_status(joypad_port_t port);
-
 #ifdef __cplusplus
 }
 #endif