freshlybakedca.ke
Git fork
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>
authored by
Lucas Seiki Oshiro
and committed by
Junio C Hamano
fba60a48
cb96e169
-4
json-writer.c
-4
json-writer.c
···
268
268
strbuf_addbuf(&jw->json, &value->json);
269
269
}
270
270
271
-
/*
272
-
* Append existing (properly terminated) JSON sub-data (object or array)
273
-
* as-is onto the given JSON data.
274
-
*/
275
271
void jw_object_sub_jw(struct json_writer *jw, const char *key,
276
272
const struct json_writer *value)
277
273
{
+143
json-writer.h
+143
json-writer.h
···
69
69
.open_stack = STRBUF_INIT, \
70
70
}
71
71
72
+
/*
73
+
* Initialize a json_writer with empty values.
74
+
*/
72
75
void jw_init(struct json_writer *jw);
76
+
77
+
/*
78
+
* Release the internal buffers of a json_writer.
79
+
*/
73
80
void jw_release(struct json_writer *jw);
74
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
+
*/
75
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
+
*/
76
94
void jw_array_begin(struct json_writer *jw, int pretty);
77
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
+
*/
78
100
void jw_object_string(struct json_writer *jw, const char *key,
79
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
+
*/
80
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
+
*/
81
115
void jw_object_double(struct json_writer *jw, const char *key, int precision,
82
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
+
*/
83
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
+
*/
84
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
+
*/
85
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
+
*/
86
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
+
*/
87
147
void jw_object_sub_jw(struct json_writer *jw, const char *key,
88
148
const struct json_writer *value);
89
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
+
*/
90
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
+
*/
91
160
void jw_object_inline_begin_array(struct json_writer *jw, const char *key);
92
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
+
*/
93
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
+
*/
94
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
+
*/
95
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
+
*/
96
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
+
*/
97
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
+
*/
98
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
+
*/
99
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
+
*/
100
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
+
*/
101
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
+
*/
102
224
void jw_array_argv(struct json_writer *jw, const char **argv);
103
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
+
*/
104
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
+
*/
105
236
void jw_array_inline_begin_array(struct json_writer *jw);
106
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
+
*/
107
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
+
*/
108
251
void jw_end(struct json_writer *jw);
109
252
110
253
#endif /* JSON_WRITER_H */