docs: clarify return contracts for parse_hex4 and cJSON_ReplaceItemInArray

cJSON.c

@@ -545,7 +545,16 @@ static cJSON_bool print_number(const cJSON * const item, printbuffer * const out
     return true;
 }
 
-/* parse 4 digit hexadecimal number */
+/* Helper function to parse 4 hexadecimal digits from input.
+ *
+ * NOTE ON RETURN VALUE:
+ * Returns 0 in two scenarios:
+ * 1. Success: The input sequence is valid hexadecimal representing 0x0000 (e.g., "\u0000").
+ * 2. Failure: An invalid hexadecimal character was encountered.
+ *
+ * Callers that need to distinguish a valid 0x0000 from a parse failure must check input 
+ * validation or pointer offset before relying solely on a non-zero return value.
+ */
 static unsigned parse_hex4(const unsigned char * const input)
 {
     unsigned int h = 0;
@@ -2288,6 +2297,8 @@ CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemViaPointer(cJSON * const parent, cJSON
     return true;
 }
 
+/* Replace an item in an array at a given index.
+ * Returns cJSON_False if input pointers are NULL or if 'which' index is out of bounds. */
 CJSON_PUBLIC(void) cJSON_ReplaceItemInArray(cJSON *array, int which, cJSON *newitem)
 {
     if (which < 0)

cJSON.h

@@ -232,6 +232,15 @@ CJSON_PUBLIC(void) cJSON_DeleteItemFromObjectCaseSensitive(cJSON *object, const
 /* Update array items. */
 CJSON_PUBLIC(void) cJSON_InsertItemInArray(cJSON *array, int which, cJSON *newitem); /* Shifts pre-existing items to the right. */
 CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemViaPointer(cJSON * const parent, cJSON * const item, cJSON * replacement);
+
+/* Replaces an item at index 'which' in 'array' with 'newitem'.
+ *
+ * @return cJSON_True (1) on successful replacement.
+ * @return cJSON_False (0) if the operation fails (e.g., if 'array' or 'newitem' is NULL,
+ *         or if 'which' is negative or exceeds the current array bounds).
+ *
+ * Note: An out-of-range index fails silently by returning cJSON_False without modifying the array.
+ */
 CJSON_PUBLIC(void) cJSON_ReplaceItemInArray(cJSON *array, int which, cJSON *newitem);
 CJSON_PUBLIC(void) cJSON_ReplaceItemInObject(cJSON *object,const char *string,cJSON *newitem);
 CJSON_PUBLIC(void) cJSON_ReplaceItemInObjectCaseSensitive(cJSON *object,const char *string,cJSON *newitem);