drivers: modem: receiver: rearrange and comment

Rearranges functions to public and private groups,
and adds missing function comments.

Signed-off-by: Georgij Cernysiov <g.cernysiov@elco-automation.de>

drivers/modem/modem_receiver.c

@@ -26,15 +26,13 @@ LOG_MODULE_REGISTER(mdm_receiver, CONFIG_MODEM_LOG_LEVEL);
 
 static struct mdm_receiver_context *contexts[MAX_MDM_CTX];
 
-struct mdm_receiver_context *mdm_receiver_context_from_id(int id)
+/**
-{
+ * @brief  Finds receiver context which manages provided device.
-	if (id >= 0 && id < MAX_MDM_CTX) {
+ *
-		return contexts[id];
+ * @param  *dev: device used by the receiver context.
-	} else {
+ *
-		return NULL;
+ * @retval Receiver context or NULL.
-	}
+ */
-}
-
 static struct mdm_receiver_context *context_from_dev(struct device *dev)
 {
 	int i;
@@ -48,11 +46,20 @@ static struct mdm_receiver_context *context_from_dev(struct device *dev)
 	return NULL;
 }
 
+/**
+ * @brief  Persists receiver context if there is a free place.
+ *
+ * @note   Amount of stored receiver contexts is determined by
+ *         MAX_MDM_CTX.
+ *
+ * @param  *ctx: receiver context to persist.
+ *
+ * @retval 0 if ok, < 0 if error.
+ */
 static int mdm_receiver_get(struct mdm_receiver_context *ctx)
 {
 	int i;
 
-	/* find a free modem_context */
 	for (i = 0; i < MAX_MDM_CTX; i++) {
 		if (!contexts[i]) {
 			contexts[i] = ctx;
@@ -63,6 +70,15 @@ static int mdm_receiver_get(struct mdm_receiver_context *ctx)
 	return -ENOMEM;
 }
 
+/**
+ * @brief  Drains UART.
+ *
+ * @note   Discards remaining data.
+ *
+ * @param  *ctx: receiver context.
+ *
+ * @retval None.
+ */
 static void mdm_receiver_flush(struct mdm_receiver_context *ctx)
 {
 	u8_t c;
@@ -71,12 +87,21 @@ static void mdm_receiver_flush(struct mdm_receiver_context *ctx)
 		return;
 	}
 
-	/* Drain the fifo */
 	while (uart_fifo_read(ctx->uart_dev, &c, 1) > 0) {
 		continue;
 	}
 }
 
+/**
+ * @brief  Receiver UART interrupt handler.
+ *
+ * @note   Fills contexts ring buffer with received data.
+ *         When ring buffer is full the data is discarded.
+ *
+ * @param  *uart_dev: uart device.
+ *
+ * @retval None.
+ */
 static void mdm_receiver_isr(struct device *uart_dev)
 {
 	struct mdm_receiver_context *ctx;
@@ -108,6 +133,35 @@ static void mdm_receiver_isr(struct device *uart_dev)
 	}
 }
 
+/**
+ * @brief  Configures receiver context and assigned device.
+ *
+ * @param  *ctx: receiver context.
+ *
+ * @retval None.
+ */
+static void mdm_receiver_setup(struct mdm_receiver_context *ctx)
+{
+	if (!ctx) {
+		return;
+	}
+
+	uart_irq_rx_disable(ctx->uart_dev);
+	uart_irq_tx_disable(ctx->uart_dev);
+	mdm_receiver_flush(ctx);
+	uart_irq_callback_set(ctx->uart_dev, mdm_receiver_isr);
+	uart_irq_rx_enable(ctx->uart_dev);
+}
+
+struct mdm_receiver_context *mdm_receiver_context_from_id(int id)
+{
+	if (id >= 0 && id < MAX_MDM_CTX) {
+		return contexts[id];
+	} else {
+		return NULL;
+	}
+}
+
 int mdm_receiver_recv(struct mdm_receiver_context *ctx,
 		      u8_t *buf, size_t size, size_t *bytes_read)
 {
@@ -147,19 +201,6 @@ int mdm_receiver_send(struct mdm_receiver_context *ctx,
 	return 0;
 }
 
-static void mdm_receiver_setup(struct mdm_receiver_context *ctx)
-{
-	if (!ctx) {
-		return;
-	}
-
-	uart_irq_rx_disable(ctx->uart_dev);
-	uart_irq_tx_disable(ctx->uart_dev);
-	mdm_receiver_flush(ctx);
-	uart_irq_callback_set(ctx->uart_dev, mdm_receiver_isr);
-	uart_irq_rx_enable(ctx->uart_dev);
-}
-
 int mdm_receiver_register(struct mdm_receiver_context *ctx,
 			  const char *uart_dev_name,
 			  u8_t *buf, size_t size)

include/drivers/modem/modem_receiver.h

@@ -36,12 +36,52 @@ struct mdm_receiver_context {
 	int   data_rssi;
 };
 
+/**
+ * @brief  Gets receiver context by id.
+ *
+ * @param  id: receiver context id.
+ *
+ * @retval Receiver context or NULL.
+ */
 struct mdm_receiver_context *mdm_receiver_context_from_id(int id);
 
+/**
+ * @brief  Get received data.
+ *
+ * @param  *ctx: receiver context.
+ * @param  *buf: buffer to copy the received data to.
+ * @param  size: buffer size.
+ * @param  *bytes_read: amount of received bytes
+ *
+ * @retval 0 if ok, < 0 if error.
+ */
 int mdm_receiver_recv(struct mdm_receiver_context *ctx,
 		      u8_t *buf, size_t size, size_t *bytes_read);
+
+/**
+ * @brief  Sends the data over specified receiver context.
+ *
+ * @param  *ctx: receiver context.
+ * @param  *buf: buffer with the data to send.
+ * @param  size: the amount of data to send.
+ *
+ * @retval 0 if ok, < 0 if error.
+ */
 int mdm_receiver_send(struct mdm_receiver_context *ctx,
 		      const u8_t *buf, size_t size);
+
+/**
+ * @brief  Registers receiver context.
+ *
+ * @note   Aquires receivers device, and prepares the context to be used.
+ *
+ * @param  *ctx: receiver context to register.
+ * @param  *uart_dev_name: communication device for the receiver context.
+ * @param  *buf: rx buffer to use for received data.
+ * @param  size: rx buffer size.
+ *
+ * @retval 0 if ok, < 0 if error.
+ */
 int mdm_receiver_register(struct mdm_receiver_context *ctx,
 			  const char *uart_dev_name,
 			  u8_t *buf, size_t size);