Mercurial > hg > ucx / file diff

--- a/src/cx/json.h	Thu Dec 26 18:32:05 2024 +0100
+++ b/src/cx/json.h	Thu Dec 26 19:26:37 2024 +0100
@@ -551,75 +551,276 @@
 }
 #endif
 
+/**
+ * Creates a new (empty) JSON object.
+ *
+ * @param allocator the allocator to use
+ * @return the new JSON object or \c NULL if allocation fails
+ */
 cx_attr_nodiscard
 CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator);
 
+/**
+ * Creates a new (empty) JSON array.
+ *
+ * @param allocator the allocator to use
+ * @return the new JSON array or \c NULL if allocation fails
+ */
 cx_attr_nodiscard
 CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator);
 
+/**
+ * Creates a new JSON number value.
+ *
+ * @param allocator the allocator to use
+ * @param num the numeric value
+ * @return the new JSON value or \c NULL if allocation fails
+ * @see cxJsonObjPutNumber()
+ * @see cxJsonArrAddNumbers()
+ */
 cx_attr_nodiscard
 CxJsonValue* cxJsonCreateNumber(const CxAllocator* allocator, double num);
 
+/**
+ * Creates a new JSON number value based on an integer.
+ *
+ * @param allocator the allocator to use
+ * @param num the numeric value
+ * @return the new JSON value or \c NULL if allocation fails
+ * @see cxJsonObjPutInteger()
+ * @see cxJsonArrAddIntegers()
+ */
 cx_attr_nodiscard
 CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num);
 
+/**
+ * Creates a new JSON string.
+ *
+ * @param allocator the allocator to use
+ * @param str the string data
+ * @return the new JSON value or \c NULL if allocation fails
+ * @see cxJsonCreateCxString()
+ * @see cxJsonObjPutString()
+ * @see cxJsonArrAddStrings()
+ */
 cx_attr_nodiscard
 cx_attr_nonnull_arg(2)
 cx_attr_cstr_arg(2)
 CxJsonValue* cxJsonCreateString(const CxAllocator* allocator, const char *str);
 
+/**
+ * Creates a new JSON string.
+ *
+ * @param allocator the allocator to use
+ * @param str the string data
+ * @return the new JSON value or \c NULL if allocation fails
+ * @see cxJsonCreateString()
+ * @see cxJsonObjPutCxString()
+ * @see cxJsonArrAddCxStrings()
+ */
 cx_attr_nodiscard
 CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str);
 
+/**
+ * Creates a new JSON literal.
+ *
+ * @param allocator the allocator to use
+ * @param lit the type of literal
+ * @return the new JSON value or \c NULL if allocation fails
+ * @see cxJsonObjPutLiteral()
+ * @see cxJsonArrAddLiterals()
+ */
 cx_attr_nodiscard
 CxJsonValue* cxJsonCreateLiteral(const CxAllocator* allocator, CxJsonLiteral lit);
 
+/**
+ * Adds number values to a JSON array.
+ *
+ * @param arr the JSON array
+ * @param num the array of values
+ * @param count the number of elements
+ * @return zero on success, non-zero on allocation failure
+ */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 int cxJsonArrAddNumbers(CxJsonValue* arr, const double* num, size_t count);
 
+/**
+ * Adds number values, of which all are integers, to a JSON array.
+ *
+ * @param arr the JSON array
+ * @param num the array of values
+ * @param count the number of elements
+ * @return zero on success, non-zero on allocation failure
+ */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 int cxJsonArrAddIntegers(CxJsonValue* arr, const int64_t* num, size_t count);
 
+/**
+ * Adds strings to a JSON array.
+ *
+ * The strings will be copied with the allocator of the array.
+ *
+ * @param arr the JSON array
+ * @param str the array of strings
+ * @param count the number of elements
+ * @return zero on success, non-zero on allocation failure
+ * @see cxJsonArrAddCxStrings()
+ */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 int cxJsonArrAddStrings(CxJsonValue* arr, const char* const* str, size_t count);
 
+/**
+ * Adds strings to a JSON array.
+ *
+ * The strings will be copied with the allocator of the array.
+ *
+ * @param arr the JSON array
+ * @param str the array of strings
+ * @param count the number of elements
+ * @return zero on success, non-zero on allocation failure
+ * @see cxJsonArrAddStrings()
+ */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 int cxJsonArrAddCxStrings(CxJsonValue* arr, const cxstring* str, size_t count);
 
+/**
+ * Adds literals to a JSON array.
+ *
+ * @param arr the JSON array
+ * @param lit the array of literal types
+ * @param count the number of elements
+ * @return zero on success, non-zero on allocation failure
+ */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 int cxJsonArrAddLiterals(CxJsonValue* arr, const CxJsonLiteral* lit, size_t count);
 
+/**
+ * Add arbitrary values to a JSON array.
+ *
+ * \note In contrast to all other add functions, this function adds the values
+ * directly to the array instead of copying them.
+ *
+ * @param arr the JSON array
+ * @param val the values
+ * @param count the number of elements
+ * @return zero on success, non-zero on allocation failure
+ */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count);
 
+/**
+ * Adds or replaces a value within a JSON object.
+ *
+ * The value will be directly added and not copied.
+ *
+ * \note If a value with the specified \p name already exists,
+ * it will be (recursively) freed with its own allocator.
+ *
+ * @param obj the JSON object
+ * @param name the name of the value
+ * @param child the value
+ * @return zero on success, non-zero on allocation failure
+ */
 cx_attr_nonnull
 int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child);
 
+/**
+ * Creates a new JSON object and adds it to an existing object.
+ *
+ * @param obj the target JSON object
+ * @param name the name of the new value
+ * @return the new value or \c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateObj()
+ */
 cx_attr_nonnull
 CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name);
 
+/**
+ * Creates a new JSON array and adds it to an object.
+ *
+ * @param obj the target JSON object
+ * @param name the name of the new value
+ * @return the new value or \c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateArr()
+ */
 cx_attr_nonnull
 CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name);
 
+/**
+ * Creates a new JSON number and adds it to an object.
+ *
+ * @param obj the target JSON object
+ * @param name the name of the new value
+ * @param num the numeric value
+ * @return the new value or \c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateNumber()
+ */
 cx_attr_nonnull
 CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num);
 
+/**
+ * Creates a new JSON number, based on an integer, and adds it to an object.
+ *
+ * @param obj the target JSON object
+ * @param name the name of the new value
+ * @param num the numeric value
+ * @return the new value or \c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateInteger()
+ */
 cx_attr_nonnull
 CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num);
 
+/**
+ * Creates a new JSON string and adds it to an object.
+ *
+ * The string data is copied.
+ *
+ * @param obj the target JSON object
+ * @param name the name of the new value
+ * @param str the string data
+ * @return the new value or \c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateString()
+ */
 cx_attr_nonnull
 cx_attr_cstr_arg(3)
 CxJsonValue* cxJsonObjPutString(CxJsonValue* obj, cxstring name, const char* str);
 
+/**
+ * Creates a new JSON string and adds it to an object.
+ *
+ * The string data is copied.
+ *
+ * @param obj the target JSON object
+ * @param name the name of the new value
+ * @param str the string data
+ * @return the new value or \c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateCxString()
+ */
 cx_attr_nonnull
 CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str);
 
+/**
+ * Creates a new JSON literal and adds it to an object.
+ *
+ * @param obj the target JSON object
+ * @param name the name of the new value
+ * @param lit the type of literal
+ * @return the new value or \c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateLiteral()
+ */
 cx_attr_nonnull
 CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit);