gh-674: Add missing documentation about return value and usage of cel…

…ix_err.

libs/utils/include/celix_convert_utils.h

@@ -72,6 +72,8 @@ CELIX_UTILS_EXPORT long celix_utils_convertStringToLong(const char* val, long de
 /**
  * @brief Convert a string to a celix_version_t.
  *
+ * In case of an error, an error message is added to celix_err.
+ *
  * @note This convert function will only convert version strings in the format major.minor.micro(.qualifier)?.
  * So the major, minor and micro are required, the qualifier is optional.
  *
@@ -93,10 +95,15 @@ CELIX_UTILS_EXPORT celix_status_t celix_utils_convertStringToVersion(const char*
  * The expected format of the string is a "," separated list of longs. Whitespace is ignored.
  * Long entries are created using celix_utils_convertStringToLong.
  *
+ * In case of an error, an error message is added to celix_err.
+ *
  * @param[in] val The string to convert.
  * @param[in] defaultValue The default value if the string is not a valid "," separated list of longs.
  * @param[out] list The converted list. If the string is not a valid list, the list will be set to a copy of the
  * defaultValue.
+ * @return CELIX_SUCCESS if the string is a valid array list of specified entry type, CELIX_ILLEGAL_ARGUMENT if otherwise,
+ * and CELIX_ENOMEM if memory could not be allocated.
+ * Note that on a CELIX_ILLEGAL_ARGUMENT the list will be set to a copy of the defaultValue.
  */
 CELIX_UTILS_EXPORT
 celix_status_t celix_utils_convertStringToLongArrayList(const char* val,
@@ -109,10 +116,15 @@ celix_status_t celix_utils_convertStringToLongArrayList(const char* val,
  * The expected format of the string is a "," separated list of doubles. Whitespace is ignored.
  * Double entries are created using celix_utils_convertStringToDouble.
  *
+ * In case of an error, an error message is added to celix_err.
+ *
  * @param[in] val The string to convert.
  * @param[in] defaultValue The default value if the string is not a valid "," separated list of doubles.
  * @param[out] list The converted list. If the string is not a valid list, the list will be set to a copy of the
  * defaultValue.
+ * @return CELIX_SUCCESS if the string is a valid array list of specified entry type, CELIX_ILLEGAL_ARGUMENT if otherwise,
+ * and CELIX_ENOMEM if memory could not be allocated.
+ * Note that on a CELIX_ILLEGAL_ARGUMENT the list will be set to a copy of the defaultValue.
  */
 CELIX_UTILS_EXPORT
 celix_status_t celix_utils_convertStringToDoubleArrayList(const char* val,
@@ -125,10 +137,15 @@ celix_status_t celix_utils_convertStringToDoubleArrayList(const char* val,
  * The expected format of the string is a "," separated list of booleans. Whitespace is ignored.
  * Boolean entries are converted using celix_utils_convertStringToBool.
  *
+ * In case of an error, an error message is added to celix_err.
+ *
  * @param[in] val The string to convert.
  * @param[in] defaultValue The default value if the string is not a valid "," separated list of booleans.
  * @param[out] list The converted list. If the string is not a valid list, the list will be set to a copy of the
  * defaultValue.
+ * @return CELIX_SUCCESS if the string is a valid array list of specified entry type, CELIX_ILLEGAL_ARGUMENT if otherwise,
+ * and CELIX_ENOMEM if memory could not be allocated.
+ * Note that on a CELIX_ILLEGAL_ARGUMENT the list will be set to a copy of the defaultValue.
  */
 CELIX_UTILS_EXPORT
 celix_status_t celix_utils_convertStringToBoolArrayList(const char* val,
@@ -144,13 +161,18 @@ celix_status_t celix_utils_convertStringToBoolArrayList(const char* val,
  * The escaped character is "\" and can be used to escape "," and "\" characters.
  * E.g. "a,b\,\\,c" will be converted to "a", "b,\" and "c".
  *
+ * In case of an error, an error message is added to celix_err.
+ *
  * @param[in] val The string to convert.
  * @param[in] defaultValue The default value if the string is not a valid "," separated list of strings.
  *                         Note that the defaultValue is copied if the string is not a valid list of string entries
  *                         and the defaultValue is expected to be configured with a removed entry callback so the
  * strings are freed.
  * @param[out] list The converted list. If the string is not a valid list, the list will be set to a copy of the
  * defaultValue.
+ * @return CELIX_SUCCESS if the string is a valid array list of specified entry type, CELIX_ILLEGAL_ARGUMENT if otherwise,
+ * and CELIX_ENOMEM if memory could not be allocated.
+ * Note that on a CELIX_ILLEGAL_ARGUMENT the list will be set to a copy of the defaultValue.
  */
 CELIX_UTILS_EXPORT
 celix_status_t celix_utils_convertStringToStringArrayList(const char* val,
@@ -164,13 +186,18 @@ celix_status_t celix_utils_convertStringToStringArrayList(const char* val,
  * Version entries are created using celix_utils_convertStringToVersion and the returned list will be configured to call
  * celix_version_destroy when entries are removed.
  *
+ * In case of an error, an error message is added to celix_err.
+ *
  * @param[in] val The string to convert.
  * @param[in] defaultValue The default value if the string is not a valid "," separated list of string parseable to
  *                         celix_version_t entries. Note that the defaultValue is copied if the string is not a valid
  *                         list of version entries and the defaultValue
  *                         is expected to be configured with a removed entry callback so the versions are freed.
  * @param[out] list The converted list. If the string is not a valid list, the list will be set to a copy of the
  * defaultValue.
+ * @return CELIX_SUCCESS if the string is a valid array list of specified entry type, CELIX_ILLEGAL_ARGUMENT if otherwise,
+ * and CELIX_ENOMEM if memory could not be allocated.
+ * Note that on a CELIX_ILLEGAL_ARGUMENT the list will be set to a copy of the defaultValue.
  */
 CELIX_UTILS_EXPORT
 celix_status_t celix_utils_convertStringToVersionArrayList(const char* val,
@@ -184,6 +211,8 @@ celix_status_t celix_utils_convertStringToVersionArrayList(const char* val,
  * CELIX_ARRAY_LIST_ELEMENT_TYPE_BOOL, CELIX_ARRAY_LIST_ELEMENT_TYPE_LONG, CELIX_ARRAY_LIST_ELEMENT_TYPE_DOUBLE,
  * or CELIX_ARRAY_LIST_ELEMENT_TYPE_VERSION.
  *
+ * In case of an error, an error message is added to celix_err.
+ *
  * @param[in] list The list to convert.
  * @return The string representation of the list. The returned string is allocated and should be freed.
  * @retrunvalue NULL if the list is NULL or if the list entry type is CELIX_ARRAY_LIST_ELEMENT_TYPE_UNDEFINED or

libs/utils/include/celix_version.h

@@ -101,7 +101,6 @@ CELIX_UTILS_EXPORT celix_version_t* celix_version_copy(const celix_version_t* ve
  */
 CELIX_UTILS_EXPORT celix_version_t* celix_version_createVersionFromString(const char *versionStr);
 
-//TODO test
 /**
  * @brief Parse a version string into a version object.
  *