json-writer: describe the usage of jw_* functions
Provide an overview of the set of functions used for manipulating `json_writer`s, by describing what functions should be used for each JSON-related task. Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Patrick Steinhardt <ps@pks.im> Helped-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> Acked-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Lucas Seiki Oshiro committed
May 15, 2025 at 22:01 UTC
da692298ac64a835378237ed4870737fb19552fc
1 file changed
+28
json-writer.h
+28
@@ -28,6 +28,34 @@
28
* object/array) -or- by building them inline in one pass. This is a
29
* personal style and/or data shape choice.
30
*
31
+ * USAGE:
32
+ * ======
33
+ *
34
+ * - Initialize the json_writer with jw_init.
35
+ *
36
+ * - Open an object as the main data structure with jw_object_begin.
37
+ * Append a key-value pair to it using the jw_object_<type> functions.
38
+ * Conclude with jw_end.
39
+ *
40
+ * - Alternatively, open an array as the main data structure with
41
+ * jw_array_begin. Append a value to it using the jw_array_<type>
42
+ * functions. Conclude with jw_end.
43
+ *
44
+ * - Append a new, unterminated array or object to the current
45
+ * object using the jw_object_inline_begin_{array, object} functions.
46
+ * Similarly, append a new, unterminated array or object to
47
+ * the current array using the jw_array_inline_begin_{array, object}
48
+ * functions.
49
+ *
50
+ * - Append other json_writer as a value to the current array or object
51
+ * using the jw_{array, object}_sub_jw functions.
52
+ *
53
+ * - Extend the current array with an null-terminated array of strings
54
+ * by using jw_array_argv or with a fixed number of elements of a
55
+ * array of string by using jw_array_argc_argv.
56
+ *
57
+ * - Release the json_writer after using it by calling jw_release.
58
+ *
59
* See t/helper/test-json-writer.c for various usage examples.
60
*
61
* LIMITATIONS: