From 7fb846a839764ea6aa2c686d7c5719dd991682c4 Mon Sep 17 00:00:00 2001
From: Tau <tau@nowhere>
Date: Sun, 23 May 2021 10:31:03 -0400
Subject: [PATCH] Document the aimeio API

This is de-facto a published API now so we have to support it.
---
 aimeio/aimeio.h | 54 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 3 deletions(-)

diff --git a/aimeio/aimeio.h b/aimeio/aimeio.h
index 7e922ed3..e8ceacac 100644
--- a/aimeio/aimeio.h
+++ b/aimeio/aimeio.h
@@ -5,14 +5,62 @@
 #include <stddef.h>
 #include <stdint.h>
 
-/* THIS API IS UNSTABLE. Please do not build alternative implementations of
-   this DLL just yet unless you are prepared to deal with API breakages. */
-
+/*
+    Initialize Aime IO provider DLL. Only called once, before any other
+    functions exported from this DLL are called.
+ */
 HRESULT aime_io_init(void);
+
+/*
+    Poll for IC cards in the vicinity.
+
+    - unit_no: Always 0 as of the current API version
+ */
 HRESULT aime_io_nfc_poll(uint8_t unit_no);
+
+/*
+    Attempt to read out a classic Aime card ID
+
+    - unit_no: Always 0 as of the current API version
+    - luid: Pointer to a ten-byte buffer that will receive the ID
+    - luid_size: Size of the buffer at *luid. Always 10.
+
+    Returns:
+
+    - S_OK if a classic Aime is present and was read successfully
+    - S_FALSE if no classic Aime card is present (*luid will be ignored)
+    - Any HRESULT error if an error occured.
+*/
 HRESULT aime_io_nfc_get_aime_id(
         uint8_t unit_no,
         uint8_t *luid,
         size_t luid_size);
+
+/*
+    Attempt to read out a FeliCa card ID ("IDm"). The following are examples
+    of FeliCa cards:
+
+    - Amuse IC (which includes new-style Aime-branded cards, among others)
+    - Smartphones with FeliCa NFC capability (uncommon outside Japan)
+    - Various Japanese e-cash cards and train passes
+
+    Parameters:
+
+    - unit_no: Always 0 as of the current API version
+    - IDm: Output parameter that will receive the card ID
+
+    Returns:
+
+    - S_OK if a FeliCa device is present and was read successfully
+    - S_FALSE if no FeliCa device is present (*IDm will be ignored)
+    - Any HRESULT error if an error occured.
+*/
 HRESULT aime_io_nfc_get_felica_id(uint8_t unit_no, uint64_t *IDm);
+
+/*
+    Change the color and brightness of the card reader's RGB lighting
+
+    - unit_no: Always 0 as of the current API version
+    - r, g, b: Primary color intensity, from 0 to 255 inclusive.
+*/
 void aime_io_led_set_color(uint8_t unit_no, uint8_t r, uint8_t g, uint8_t b);