From: Lucas Seiki Oshiro Date: Fri, 16 May 2025 01:01:58 +0000 (-0300) Subject: json-writer: add docstrings to jw_* functions X-Git-Tag: v2.50.0-rc0~19^2~1 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fba60a4841ce2185200e82cdb80428e9819233f8;p=thirdparty%2Fgit.git json-writer: add docstrings to jw_* functions Add a docstring for each function that manipulates json_writers. Helped-by: Junio C Hamano Helped-by: Patrick Steinhardt Helped-by: Karthik Nayak Signed-off-by: Lucas Seiki Oshiro Acked-by: Karthik Nayak Signed-off-by: Junio C Hamano --- diff --git a/json-writer.c b/json-writer.c index 8c5187e9fd..34577dc25f 100644 --- a/json-writer.c +++ b/json-writer.c @@ -268,10 +268,6 @@ static void append_sub_jw(struct json_writer *jw, strbuf_addbuf(&jw->json, &value->json); } -/* - * Append existing (properly terminated) JSON sub-data (object or array) - * as-is onto the given JSON data. - */ void jw_object_sub_jw(struct json_writer *jw, const char *key, const struct json_writer *value) { diff --git a/json-writer.h b/json-writer.h index 04413bd1af..0e8e6c3ddc 100644 --- a/json-writer.h +++ b/json-writer.h @@ -69,42 +69,185 @@ struct json_writer .open_stack = STRBUF_INIT, \ } +/* + * Initialize a json_writer with empty values. + */ void jw_init(struct json_writer *jw); + +/* + * Release the internal buffers of a json_writer. + */ void jw_release(struct json_writer *jw); +/* + * Begin the json_writer using an object as the top-level data structure. If + * pretty is set to 1, the result will be a human-readable and indented JSON, + * and if it is set to 0 the result will be minified single-line JSON. + */ void jw_object_begin(struct json_writer *jw, int pretty); + +/* + * Begin the json_writer using an array as the top-level data structure. If + * pretty is set to 1, the result will be a human-readable and indented JSON, + * and if it is set to 0 the result will be minified single-line JSON. + */ void jw_array_begin(struct json_writer *jw, int pretty); +/* + * Append a string field to the current object of the json_writer, given its key + * and its value. Trigger a BUG when not in an object. + */ void jw_object_string(struct json_writer *jw, const char *key, const char *value); + +/* + * Append an int field to the current object of the json_writer, given its key + * and its value. Trigger a BUG when not in an object. + */ void jw_object_intmax(struct json_writer *jw, const char *key, intmax_t value); + +/* + * Append a double field to the current object of the json_writer, given its key + * and its value. The precision parameter defines the number of significant + * digits, where -1 can be used for maximum precision. Trigger a BUG when not in + * an object. + */ void jw_object_double(struct json_writer *jw, const char *key, int precision, double value); + +/* + * Append a boolean field set to true to the current object of the json_writer, + * given its key. Trigger a BUG when not in an object. + */ void jw_object_true(struct json_writer *jw, const char *key); + +/* + * Append a boolean field set to false to the current object of the json_writer, + * given its key. Trigger a BUG when not in an object. + */ void jw_object_false(struct json_writer *jw, const char *key); + +/* + * Append a boolean field to the current object of the json_writer, given its + * key and its value. Trigger a BUG when not in an object. + */ void jw_object_bool(struct json_writer *jw, const char *key, int value); + +/* + * Append a null field to the current object of the json_writer, given its key. + * Trigger a BUG when not in an object. + */ void jw_object_null(struct json_writer *jw, const char *key); + +/* + * Append a field to the current object of the json_writer, given its key and + * another json_writer that represents its content. Trigger a BUG when not in + * an object. + */ void jw_object_sub_jw(struct json_writer *jw, const char *key, const struct json_writer *value); +/* + * Start an object as the value of a field in the current object of the + * json_writer. Trigger a BUG when not in an object. + */ void jw_object_inline_begin_object(struct json_writer *jw, const char *key); + +/* + * Start an array as the value of a field in the current object of the + * json_writer. Trigger a BUG when not in an object. + */ void jw_object_inline_begin_array(struct json_writer *jw, const char *key); +/* + * Append a string value to the current array of the json_writer. Trigger a BUG + * when not in an array. + */ void jw_array_string(struct json_writer *jw, const char *value); + +/* + * Append an int value to the current array of the json_writer. Trigger a BUG + * when not in an array. + */ void jw_array_intmax(struct json_writer *jw, intmax_t value); + +/* + * Append a double value to the current array of the json_writer. The precision + * parameter defines the number of significant digits, where -1 can be used for + * maximum precision. Trigger a BUG when not in an array. + */ void jw_array_double(struct json_writer *jw, int precision, double value); + +/* + * Append a true value to the current array of the json_writer. Trigger a BUG + * when not in an array. + */ void jw_array_true(struct json_writer *jw); + +/* + * Append a false value to the current array of the json_writer. Trigger a BUG + * when not in an array. + */ void jw_array_false(struct json_writer *jw); + +/* + * Append a boolean value to the current array of the json_writer. Trigger a BUG + * when not in an array. + */ void jw_array_bool(struct json_writer *jw, int value); + +/* + * Append a null value to the current array of the json_writer. Trigger a BUG + * when not in an array. + */ void jw_array_null(struct json_writer *jw); + +/* + * Append a json_writer as a value to the current array of the + * json_writer. Trigger a BUG when not in an array. + */ void jw_array_sub_jw(struct json_writer *jw, const struct json_writer *value); + +/* + * Append the first argc values from the argv array of strings to the current + * array of the json_writer. Trigger a BUG when not in an array. + * + * This function does not provide safety for cases where the array has less than + * argc values. + */ void jw_array_argc_argv(struct json_writer *jw, int argc, const char **argv); + +/* + * Append a null-terminated array of strings to the current array of the + * json_writer. Trigger a BUG when not in an array. + */ void jw_array_argv(struct json_writer *jw, const char **argv); +/* + * Start an object as a value in the current array of the json_writer. Trigger a + * BUG when not in an array. + */ void jw_array_inline_begin_object(struct json_writer *jw); + +/* + * Start an array as a value in the current array. Trigger a BUG when not in an + * array. + */ void jw_array_inline_begin_array(struct json_writer *jw); +/* + * Return whether the json_writer is terminated. In other words, if the all the + * objects and arrays are already closed. + */ int jw_is_terminated(const struct json_writer *jw); + +/* + * Terminates the current object or array of the json_writer. In other words, + * append a ] if the current array is not closed or } if the current object + * is not closed. + * + * Abort the execution if there's no object or array that can be terminated. + */ void jw_end(struct json_writer *jw); #endif /* JSON_WRITER_H */