modem: modem_pipe: Update documentation

This commit improves the documentation in the header for the
modem_pipe to include return value descriptions and notes
regarding when specific events are invoked resulting from
calls to the modem_pipe API.

Signed-off-by: Bjarki Arge Andreasen <bjarkix123@gmail.com>

include/zephyr/modem/pipe.h

@@ -69,6 +69,9 @@ void modem_pipe_init(struct modem_pipe *pipe, void *data, struct modem_pipe_api
  * @brief Open pipe
  *
  * @param pipe Pipe instance
+ *
+ * @retval 0 if pipe was successfully opened or was already open
+ * @retval -errno code otherwise
  */
 int modem_pipe_open(struct modem_pipe *pipe);
 
@@ -76,6 +79,12 @@ int modem_pipe_open(struct modem_pipe *pipe);
  * @brief Open pipe asynchronously
  *
  * @param pipe Pipe instance
+ *
+ * @note The MODEM_PIPE_EVENT_OPENED event is invoked immediately if pipe is
+ * already opened.
+ *
+ * @retval 0 if pipe open was called successfully or pipe was already open
+ * @retval -errno code otherwise
  */
 int modem_pipe_open_async(struct modem_pipe *pipe);
 
@@ -85,6 +94,9 @@ int modem_pipe_open_async(struct modem_pipe *pipe);
  * @param pipe Pipe instance
  * @param callback Callback called when pipe event occurs
  * @param user_data Free to use user data passed with callback
+ *
+ * @note The MODEM_PIPE_EVENT_RECEIVE_READY event is invoked immediately if pipe has pending
+ * data ready to receive.
  */
 void modem_pipe_attach(struct modem_pipe *pipe, modem_pipe_api_callback callback, void *user_data);
 
@@ -127,6 +139,9 @@ void modem_pipe_release(struct modem_pipe *pipe);
  * @brief Close pipe
  *
  * @param pipe Pipe instance
+ *
+ * @retval 0 if pipe open was called closed or pipe was already closed
+ * @retval -errno code otherwise
  */
 int modem_pipe_close(struct modem_pipe *pipe);
 
@@ -134,6 +149,12 @@ int modem_pipe_close(struct modem_pipe *pipe);
  * @brief Close pipe asynchronously
  *
  * @param pipe Pipe instance
+ *
+ * @note The MODEM_PIPE_EVENT_CLOSED event is invoked immediately if pipe is
+ * already closed.
+ *
+ * @retval 0 if pipe close was called successfully or pipe was already closed
+ * @retval -errno code otherwise
  */
 int modem_pipe_close_async(struct modem_pipe *pipe);