Add api docs

src/driver/dpf/dpf_device.c

@@ -124,30 +124,27 @@ static const uint8_t SCSI_CMD_READ[16] = {
     0x00, 0x00, 0x00, 0x00
 };
 
-int32_t dpf_device_acquire_dimensions(dpf_device_t *device) {
-//#define BUFFER_GET_WIDTH(buffer) (buffer[0] | (buffer[1] << 8U))
-//#define BUFFER_GET_HEIGHT(buffer) (buffer[2] | (buffer[3] << 8U))
+int32_t dpf_device_acquire_dimensions(const dpf_device_ptr_t device) {
 
     uint8_t buffer[5];
     const int32_t result = warp_scsi_read(device->scsi_device, SCSI_CMD_READ, sizeof(SCSI_CMD_READ), buffer, 5);
     if(result != 0) {
         log_warn("Get device dimensions failed.");
-        return -1;
+        return result;
     }
 
     // Device use short type, do the trick
     const uint16_t* data = (uint16_t *) buffer;
     const uint32_t width = data[0];
     const uint32_t height = data[1];
-    //       unsigned int width = BUFFER_GET_WIDTH(buffer);
-    //       unsigned int height = BUFFER_GET_HEIGHT(buffer);
 
     device->screen_width = width;
     device->screen_height = height;
 
     const uint32_t buffer_len = width * height * DPF_BYTE_PRE_PIXEL;
     device->buffer_len = buffer_len;
     if (device->buffer != NULL) free(device->buffer);
+
     device->buffer = (uint8_t *) malloc(buffer_len);
     if (!device->buffer) {
         log_error("Could not allocate screen buffer.");
@@ -202,7 +199,7 @@ uint8_t *dpf_device_get_buffer(const dpf_device_t *device) {
     return device->buffer;
 }
 
-int32_t dpf_device_get_brightness(const dpf_device_t *device) {
+int32_t dpf_device_get_brightness(const dpf_device_ptr_t device) {
     return device->brightness;
 }
 

src/driver/dpf/dpf_device.h

@@ -12,18 +12,55 @@ typedef struct dpf_device_t dpf_device_t;
 
 typedef dpf_device_t* dpf_device_ptr_t;
 
-int32_t dpf_device_open(libusb_device *device, dpf_device_t **new_device);
-
-// Ask the screen it's dimension
-int32_t dpf_device_acquire_dimensions(dpf_device_t *device);
-
-// Set back-light brightness
-int32_t dpf_device_set_brightness(dpf_device_t *device, uint32_t brightness);
+/**
+ * Create a new DPF device
+ *
+ * @param device usb device
+ * @param new_device dpf device handle
+ * @return if success, returns 0
+ */
+int32_t dpf_device_open(libusb_device *device, dpf_device_ptr_t *new_device);
+
+/**
+ * Ask the screen it's dimension and re-create the framebuffer
+ *
+ * @param device DPF device
+ * @return if success, returns 0
+ */
+int32_t dpf_device_acquire_dimensions(dpf_device_ptr_t device);
 
-int32_t dpf_device_get_brightness(const dpf_device_t *device);
+/**
+ * Set back-light brightness
+ *
+ * @param device DPF device
+ * @param brightness 0-7, 0 means off
+ * @return if success, returns 0
+ */
+int32_t dpf_device_set_brightness(dpf_device_ptr_t device, uint32_t brightness);
+
+/**
+ * Get current brightness level (cached in context)
+ *
+ * @param device DPF device
+ * @return brightness level
+ */
+int32_t dpf_device_get_brightness(dpf_device_ptr_t device);
 
+/**
+ * Set default background color, the color when screen flushing uses.
+ *
+ * @param device DPF device
+ * @param r red (0 - 255)
+ * @param g green (0 - 255)
+ * @param b blue (0 - 255)
+ */
 void dpf_device_set_background_color(dpf_device_ptr_t device, uint8_t r, uint8_t g, uint8_t b);
 
+/**
+ * Get current background color
+ * @param device DPF device
+ * @return RGBa value in a whole uint
+ */
 uint32_t *dpf_device_get_background_color(dpf_device_t *device);
 
 int32_t dpf_device_bulk_transfer(dpf_device_t *device, const uint8_t *buffer, uint32_t x0, uint32_t y0, uint32_t x1, uint32_t y1);