Clarify API contract

Signed-off-by: Ivan Santiago Paunovic <ivanpauno@ekumenlabs.com>
ros2 · Jul 8, 2020 · 57ed269 · 57ed269
1 parent d795983
commit 57ed269
Showing 1 changed file with 19 additions and 9 deletions.
diff --git a/rcl/include/rcl/log_level.h b/rcl/include/rcl/log_level.h
@@ -84,7 +84,9 @@ rcl_get_zero_initialized_log_levels();
  * \param[in] logger_count Number of logger settings to be allocated.
  *  This reserves memory for logger_settings, but doesn't initialize it.
  * \return `RCL_RET_OK` if the structure was initialized successfully, or
- * \return `RCL_RET_INVALID_ARGUMENT` if log_levels or allocator are invalid, or
+ * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is NULL, or
+ *  log_levels contains initialized memory, or
+ *  allocator is invalid, or
  * \return `RCL_RET_BAD_ALLOC` if allocating memory failed.
  */
 RCL_PUBLIC
@@ -105,9 +107,12 @@ rcl_log_levels_init(
  *
  * \param[in] src The structure to be copied.
  *  Its allocator is used to copy memory into the new structure.
- * \param[out] dst A zero-initialized log levels structure to be copied into.
+ * \param[out] dst A log levels structure to be copied into.
  * \return `RCL_RET_OK` if the structure was copied successfully, or
- * \return `RCL_RET_INVALID_ARGUMENT` if src or dst are invalid, or
+ * \return `RCL_RET_INVALID_ARGUMENT` if src is NULL, or
+ *  if src allocator is invalid, or
+ *  if dst is NULL, or
+ *  if dst contains already allocated memory, or
  * \return `RCL_RET_BAD_ALLOC` if allocating memory failed.
  */
 RCL_PUBLIC
@@ -127,7 +132,8 @@ rcl_log_levels_copy(const rcl_log_levels_t * src, rcl_log_levels_t * dst);
  *
  * \param[in] log_levels The structure which its resources have to be deallocated.
  * \return `RCL_RET_OK` if the memory was successfully freed, or
- * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is invalid.
+ * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is NULL, or
+ *  if ist allocator is invalid and the structure contains initialized memory.
  */
 RCL_PUBLIC
 rcl_ret_t
@@ -145,7 +151,7 @@ rcl_log_levels_fini(rcl_log_levels_t * log_levels);
  *
  * \param[in] log_levels The structure to be shrunk.
  * \return `RCL_RET_OK` if the memory was successfully shrunk, or
- * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is invalid, or
+ * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is NULL or if its allocator is invalid, or
  * \return `RCL_RET_BAD_ALLOC` if reallocating memory failed.
  */
 RCL_PUBLIC
@@ -162,12 +168,16 @@ rcl_log_levels_shrink_to_size(rcl_log_levels_t * log_levels);
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param[in] log_levels The structure to be added.
- * \param[in] logger_name Name for the logger.
- * \param[in] log_level Minimum log level severity.
+ * \param[in] log_levels The structure where to set the logger log level.
+ * \param[in] logger_name Name for the logger, a copy of it will be stored in the structure.
+ * \param[in] log_level Minimum log level severity to be set for logger_name.
  * \return `RCL_RET_OK` if add logger setting successfully, or
  * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or
- * \return `RCL_RET_INVALID_ARGUMENT` if log_levels or logger_name are invalid.
+ * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is NULL, or
+ *   if log_levels was not initialized, or
+ *   if log_levels allocator is invalid, or
+ *   if logger_name is NULL, or
+ * \return `RCL_RET_ERROR` if the log_levels structure is already full.
  */
 RCL_PUBLIC
 rcl_ret_t