lwm2m_carrier: doc: documentation improvements

- Aligned the use of "retval 0" closer to the NCS codebase style.
- Corrected some functions which can return a positive integer,
  such as length (as opposed to just "0 If success").
- Added documentation for some undocumented return values.
- Minor tweaks for consistendy such as spacing, and ms to milliseconds.

Signed-off-by: Håvard Vermeer <[email protected]>

Author: nordic-hani

lib/bin/lwm2m_carrier/include/lwm2m_os.h

@@ -188,7 +188,8 @@ typedef void (*lwm2m_os_pdn_event_handler_t)
  * @param[out] cid The ID of the new PDP context.
  * @param      cb  Optional event handler.
  *
- * @retval  0      If success.
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a negative error code is returned.
  */
 int lwm2m_os_pdn_ctx_create(uint8_t *cid, lwm2m_os_pdn_event_handler_t cb);
 
@@ -199,7 +200,8 @@ int lwm2m_os_pdn_ctx_create(uint8_t *cid, lwm2m_os_pdn_event_handler_t cb);
  * @param apn    The Access Point Name to configure the PDP context with.
  * @param family The family to configure the PDN context for.
  *
- * @retval  0      If success.
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a negative error code is returned.
  */
 int lwm2m_os_pdn_ctx_configure(uint8_t cid, const char *apn, enum lwm2m_os_pdn_fam family);
 
@@ -208,7 +210,8 @@ int lwm2m_os_pdn_ctx_configure(uint8_t cid, const char *apn, enum lwm2m_os_pdn_f
  *
  * @param cid The PDP context to destroy.
  *
- * @retval  0      If success.
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a negative error code is returned.
  */
 int lwm2m_os_pdn_ctx_destroy(uint8_t cid);
 
@@ -283,8 +286,8 @@ int lwm2m_os_sem_init(lwm2m_os_sem_t **sem, unsigned int initial_count, unsigned
  * @brief Take a semaphore.
  *
  * @param sem     Address of the semaphore.
- * @param timeout Timeout in ms, or -1 for forever, in which case the semaphore is taken for as long
- *                as necessary.
+ * @param timeout Timeout in milliseconds, or -1 for forever, in which case the semaphore is taken
+ *                for as long as necessary.
  *
  * @retval  0      Semaphore taken.
  * @retval -EBUSY  Returned without waiting.
@@ -308,35 +311,47 @@ void lwm2m_os_sem_reset(lwm2m_os_sem_t *sem);
 
 /**
  * @brief Get uptime, in milliseconds.
+ *
+ * @return Current uptime.
  */
 int64_t lwm2m_os_uptime_get(void);
 
 /**
  * @brief Get uptime delta, in milliseconds.
+ *
+ * @param[in] ref Pointer to a reference time, which is updated to the current
+ *                uptime upon return.
+ *
+ * @return Elapsed time.
  */
 int64_t lwm2m_os_uptime_delta(int64_t *ref);
 
 /**
- * @brief Put a thread to a sleep.
+ * @brief Put a thread to sleep.
  *
  * @param ms Desired duration of sleep in milliseconds.
+ *
+ * @return 0 if the requested duration has elapsed, or, if the thread was woken up before the
+ *         desired duration @c ms, the remaining duration left to sleep is returned.
  */
 int lwm2m_os_sleep(int ms);
 
 /**
- * @brief Reboot system.
+ * @brief Reboot the system.
  */
 void lwm2m_os_sys_reset(void);
 
 /**
  * @brief Get a random value.
+ *
+ * @return A random 32-bit value.
  */
 uint32_t lwm2m_os_rand_get(void);
 
 /**
  * @brief Delete a non-volatile storage entry.
  *
- * @param[in] id of the entry to be deleted.
+ * @param[in] id ID of the entry to be deleted.
  *
  * @retval 0 If the operation was successful.
  *           Otherwise, a negative error code is returned.
@@ -346,7 +361,7 @@ int lwm2m_os_storage_delete(uint16_t id);
 /**
  * @brief Read an entry from non-volatile storage.
  *
- * @param[in]     id   of the entry to be read.
+ * @param[in]     id   ID of the entry to be read.
  * @param[out]    data Pointer to data buffer.
  * @param[in,out] len  Number of bytes to be read.
  *
@@ -385,6 +400,8 @@ void lwm2m_os_timer_get(lwm2m_os_timer_handler_t handler, lwm2m_os_timer_t **tim
 
 /**
  * @brief Release a timer task.
+ *
+ * @param timer Timer task to be released.
  */
 void lwm2m_os_timer_release(lwm2m_os_timer_t *timer);
 
@@ -393,7 +410,7 @@ void lwm2m_os_timer_release(lwm2m_os_timer_t *timer);
  *
  * @param work_q Workqueue.
  * @param timer  Timer task.
- * @param delay  Delay before submitting the task in ms.
+ * @param delay  Delay before submitting the task in milliseconds.
  *
  * @retval  0      Work placed on queue, already on queue or already running.
  * @retval -EINVAL Timer or work_q not found.
@@ -403,7 +420,7 @@ int lwm2m_os_timer_start_on_q(lwm2m_os_work_q_t *work_q, lwm2m_os_timer_t *timer
 /**
  * @brief Cancel a timer run.
  *
- * @param timer Timer task.
+ * @param timer Timer task to cancel.
  * @param sync  If true, wait for active tasks to finish before canceling.
  */
 void lwm2m_os_timer_cancel(lwm2m_os_timer_t *timer, bool sync);
@@ -413,7 +430,7 @@ void lwm2m_os_timer_cancel(lwm2m_os_timer_t *timer, bool sync);
  *
  * @param timer Timer task.
  *
- * @return Time remaining in ms.
+ * @return Time remaining in milliseconds.
  */
 int64_t lwm2m_os_timer_remaining(lwm2m_os_timer_t *timer);
 
@@ -422,23 +439,24 @@ int64_t lwm2m_os_timer_remaining(lwm2m_os_timer_t *timer);
  *
  * @param timer Timer task.
  *
- * @retval  true  If a timer task is pending.
+ * @retval true  If the timer task is pending.
+ * @retval false If the timer task is idle.
  */
 bool lwm2m_os_timer_is_pending(lwm2m_os_timer_t *timer);
 
 /**
  * @brief Initialize AT command driver.
  *
- * @retval  0      If success.
- * @retval -EIO    If AT command driver initialization failed.
+ * @retval  0   If success.
+ * @retval -EIO If AT command driver initialization failed.
  */
 int lwm2m_os_at_init(lwm2m_os_at_handler_callback_t callback);
 
 /**
  * @brief Register as an SMS client/listener.
  *
- * @retval  0      If success.
- * @retval -EIO    If unable to register as SMS listener.
+ * @retval  0   If success.
+ * @retval -EIO If unable to register as SMS listener.
  */
 int lwm2m_os_sms_client_register(lwm2m_os_sms_callback_t lib_callback, void *context);
 
@@ -450,38 +468,42 @@ void lwm2m_os_sms_client_deregister(int handle);
 /**
  * @brief Establish a connection with the server and download a file.
  *
- * @retval  0      If success.
+ *  @retval 0 If the operation was successful.
+ *            Otherwise, a negative error code is returned.
  */
 int lwm2m_os_download_get(const char *uri, const struct lwm2m_os_download_cfg *cfg, size_t from);
 
 /**
  * @brief Disconnect from the server.
  *
- * @retval  0      If success.
+ *  @retval 0 If the operation was successful.
+ *            Otherwise, a negative error code is returned.
  */
 int lwm2m_os_download_disconnect(void);
 
 /**
  * @brief Initialize the download client.
  *
- * @retval  0      If success.
+ *  @retval 0 If the operation was successful.
+ *            Otherwise, a negative error code is returned.
  */
 int lwm2m_os_download_init(lwm2m_os_download_callback_t lib_callback);
 
 /**
  * @brief Retrieve size of file being downloaded.
  *
- * @param size Size of the file being downloaded.
+ * @param[out] size Size of the file being downloaded.
  *
- * @retval  0      If success.
+ * @retval 0 If the operation was successful.
+ *           Otherwise, a negative error code is returned.
  */
 int lwm2m_os_download_file_size_get(size_t *size);
 
 /**
  * @brief Check if UICC LwM2M bootstrap is enabled.
  *
- * @retval  true  If enabled
- * @retval  false If disabled
+ * @retval true  If enabled
+ * @retval false If disabled
  */
 bool lwm2m_os_uicc_bootstrap_is_enabled(void);
 
@@ -491,7 +513,7 @@ bool lwm2m_os_uicc_bootstrap_is_enabled(void);
  * @param p_buffer    Buffer to store UICC LwM2M bootstrap record.
  * @param buffer_size Size of the buffer in bytes.
  *
- * @retval  0      If success.
+ * @retval Length of the record. On error, returns a negative value.
  */
 int lwm2m_os_uicc_bootstrap_read(uint8_t *p_buffer, int buffer_size);
 
@@ -557,10 +579,10 @@ struct __attribute__((__packed__)) lwm2m_os_dfu_header {
 /**
  * @brief Find the image type for the buffer of bytes received.
  *
- * @param[in]  buf     A buffer of bytes which are the start of a binary firmware image.
- * @param[in]  len     The length of the provided buffer.
- * @param[out] header  DFU image header descriptor. Only applicable to MCUboot-style upgrades over
- *                     multiple files.
+ * @param[in]  buf    A buffer of bytes which are the start of a binary firmware image.
+ * @param[in]  len    The length of the provided buffer.
+ * @param[out] header DFU image header descriptor. Only applicable to MCUboot-style upgrades over
+ *                    multiple files.
  *
  * @return Identifier for a supported image type or LWM2M_OS_DFU_IMG_TYPE_NONE if
  *         image type is not recognized or not supported.
@@ -628,7 +650,10 @@ int lwm2m_os_dfu_pause(void);
 /**
  * @brief Schedule update for uploaded image.
  *
- * @retval  0  If success.
+ * @retval  0      If the update was scheduled successfully.
+ * @retval -EINVAL If the data needed to perform the update was incomplete.
+ * @retval -EACCES If the DFU process was not in progress.
+ * @retval -EIO    Internal error.
  */
 int lwm2m_os_dfu_schedule_update(void);
 
@@ -640,7 +665,8 @@ void lwm2m_os_dfu_reset(void);
 /**
  * @brief Validate the application image update.
  *
- * @retval  true  If the application image was updated successfully.
+ * @retval true  If the application image was updated successfully.
+ * @retval false If the application image was not updated successfully.
  */
 bool lwm2m_os_dfu_application_update_validate(void);