json-writer: add docstrings to jw_* functions
Add a docstring for each function that manipulates json_writers. 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
fba60a4841ce2185200e82cdb80428e9819233f8
2 files changed
+143
-4
json-writer.c
-4
@@ -268,10 +268,6 @@ static void append_sub_jw(struct json_writer *jw,
268
strbuf_addbuf(&jw->json, &value->json);
269
}
270
271
-/*
272
- * Append existing (properly terminated) JSON sub-data (object or array)
273
- * as-is onto the given JSON data.
274
- */
271
void jw_object_sub_jw(struct json_writer *jw, const char *key,
272
const struct json_writer *value)
273
{
json-writer.h
+143
@@ -69,42 +69,185 @@ struct json_writer
69
.open_stack = STRBUF_INIT, \
70
}
71
72
+/*
73
+ * Initialize a json_writer with empty values.
74
+ */
75
void jw_init(struct json_writer *jw);
76
+
77
+/*
78
+ * Release the internal buffers of a json_writer.
79
+ */
80
void jw_release(struct json_writer *jw);
81
82
+/*
83
+ * Begin the json_writer using an object as the top-level data structure. If
84
+ * pretty is set to 1, the result will be a human-readable and indented JSON,
85
+ * and if it is set to 0 the result will be minified single-line JSON.
86
+ */
87
void jw_object_begin(struct json_writer *jw, int pretty);
88
+
89
+/*
90
+ * Begin the json_writer using an array as the top-level data structure. If
91
+ * pretty is set to 1, the result will be a human-readable and indented JSON,
92
+ * and if it is set to 0 the result will be minified single-line JSON.
93
+ */
94
void jw_array_begin(struct json_writer *jw, int pretty);
95
96
+/*
97
+ * Append a string field to the current object of the json_writer, given its key
98
+ * and its value. Trigger a BUG when not in an object.
99
+ */
100
void jw_object_string(struct json_writer *jw, const char *key,
101
const char *value);
102
+
103
+/*
104
+ * Append an int field to the current object of the json_writer, given its key
105
+ * and its value. Trigger a BUG when not in an object.
106
+ */
107
void jw_object_intmax(struct json_writer *jw, const char *key, intmax_t value);
108
+
109
+/*
110
+ * Append a double field to the current object of the json_writer, given its key
111
+ * and its value. The precision parameter defines the number of significant
112
+ * digits, where -1 can be used for maximum precision. Trigger a BUG when not in
113
+ * an object.
114
+ */
115
void jw_object_double(struct json_writer *jw, const char *key, int precision,
116
double value);
117
+
118
+/*
119
+ * Append a boolean field set to true to the current object of the json_writer,
120
+ * given its key. Trigger a BUG when not in an object.
121
+ */
122
void jw_object_true(struct json_writer *jw, const char *key);
123
+
124
+/*
125
+ * Append a boolean field set to false to the current object of the json_writer,
126
+ * given its key. Trigger a BUG when not in an object.
127
+ */
128
void jw_object_false(struct json_writer *jw, const char *key);
129
+
130
+/*
131
+ * Append a boolean field to the current object of the json_writer, given its
132
+ * key and its value. Trigger a BUG when not in an object.
133
+ */
134
void jw_object_bool(struct json_writer *jw, const char *key, int value);
135
+
136
+/*
137
+ * Append a null field to the current object of the json_writer, given its key.
138
+ * Trigger a BUG when not in an object.
139
+ */
140
void jw_object_null(struct json_writer *jw, const char *key);
141
+
142
+/*
143
+ * Append a field to the current object of the json_writer, given its key and
144
+ * another json_writer that represents its content. Trigger a BUG when not in
145
+ * an object.
146
+ */
147
void jw_object_sub_jw(struct json_writer *jw, const char *key,
148
const struct json_writer *value);
149
150
+/*
151
+ * Start an object as the value of a field in the current object of the
152
+ * json_writer. Trigger a BUG when not in an object.
153
+ */
154
void jw_object_inline_begin_object(struct json_writer *jw, const char *key);
155
+
156
+/*
157
+ * Start an array as the value of a field in the current object of the
158
+ * json_writer. Trigger a BUG when not in an object.
159
+ */
160
void jw_object_inline_begin_array(struct json_writer *jw, const char *key);
161
162
+/*
163
+ * Append a string value to the current array of the json_writer. Trigger a BUG
164
+ * when not in an array.
165
+ */
166
void jw_array_string(struct json_writer *jw, const char *value);
167
+
168
+/*
169
+ * Append an int value to the current array of the json_writer. Trigger a BUG
170
+ * when not in an array.
171
+ */
172
void jw_array_intmax(struct json_writer *jw, intmax_t value);
173
+
174
+/*
175
+ * Append a double value to the current array of the json_writer. The precision
176
+ * parameter defines the number of significant digits, where -1 can be used for
177
+ * maximum precision. Trigger a BUG when not in an array.
178
+ */
179
void jw_array_double(struct json_writer *jw, int precision, double value);
180
+
181
+/*
182
+ * Append a true value to the current array of the json_writer. Trigger a BUG
183
+ * when not in an array.
184
+ */
185
void jw_array_true(struct json_writer *jw);
186
+
187
+/*
188
+ * Append a false value to the current array of the json_writer. Trigger a BUG
189
+ * when not in an array.
190
+ */
191
void jw_array_false(struct json_writer *jw);
192
+
193
+/*
194
+ * Append a boolean value to the current array of the json_writer. Trigger a BUG
195
+ * when not in an array.
196
+ */
197
void jw_array_bool(struct json_writer *jw, int value);
198
+
199
+/*
200
+ * Append a null value to the current array of the json_writer. Trigger a BUG
201
+ * when not in an array.
202
+ */
203
void jw_array_null(struct json_writer *jw);
204
+
205
+/*
206
+ * Append a json_writer as a value to the current array of the
207
+ * json_writer. Trigger a BUG when not in an array.
208
+ */
209
void jw_array_sub_jw(struct json_writer *jw, const struct json_writer *value);
210
+
211
+/*
212
+ * Append the first argc values from the argv array of strings to the current
213
+ * array of the json_writer. Trigger a BUG when not in an array.
214
+ *
215
+ * This function does not provide safety for cases where the array has less than
216
+ * argc values.
217
+ */
218
void jw_array_argc_argv(struct json_writer *jw, int argc, const char **argv);
219
+
220
+/*
221
+ * Append a null-terminated array of strings to the current array of the
222
+ * json_writer. Trigger a BUG when not in an array.
223
+ */
224
void jw_array_argv(struct json_writer *jw, const char **argv);
225
226
+/*
227
+ * Start an object as a value in the current array of the json_writer. Trigger a
228
+ * BUG when not in an array.
229
+ */
230
void jw_array_inline_begin_object(struct json_writer *jw);
231
+
232
+/*
233
+ * Start an array as a value in the current array. Trigger a BUG when not in an
234
+ * array.
235
+ */
236
void jw_array_inline_begin_array(struct json_writer *jw);
237
238
+/*
239
+ * Return whether the json_writer is terminated. In other words, if the all the
240
+ * objects and arrays are already closed.
241
+ */
242
int jw_is_terminated(const struct json_writer *jw);
243
+
244
+/*
245
+ * Terminates the current object or array of the json_writer. In other words,
246
+ * append a ] if the current array is not closed or } if the current object
247
+ * is not closed.
248
+ *
249
+ * Abort the execution if there's no object or array that can be terminated.
250
+ */
251
void jw_end(struct json_writer *jw);
252
253
#endif /* JSON_WRITER_H */