Re: [GSoC PATCH v2 1/2] json-writer: add docstrings to jw_* functions

[Karthik Nayak <karthik.188@xxxxxxxxx>]

Lucas Seiki Oshiro <lucasseikioshiro@xxxxxxxxx> writes:

[snip]

> +/*
> + * Append a double field to the current object of the json_writer, given its key
> + * and its value. The precision parameter can be used for specifying the number
> + * of decimals after the point, using -1 for formatting with the maximum
> + * precision available.

Nit: I would perhaps switch s/using/use to make it present tense and
easier to read.

[snip]

> +/*
> + * Append a field to the current object of the json_writer, given its key and
> + * another json_writer that represents its content.
> + */
>  void jw_object_sub_jw(struct json_writer *jw, const char *key,
>  		      const struct json_writer *value);
>

`json-writer.c` also has a docstring for this function, perhaps we
can remove that and keep the header file as the source of truth?

> +/*
> + * Start an object as the value of a field in the current object of the
> + * json_writer, given the field key.
> + */
>  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, given the field key.
> + */
>  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.
> + */
>  void jw_array_string(struct json_writer *jw, const char *value);
> +
> +/*
> + * Append an int value to the current array of the json_writer.
> + */
>  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 can be used for specifying the number of decimals after the point,
> + * using -1 for formatting with the maximum precision available.
> + */

Nit: wondering if it might be shorter/nicer to say

  The precision parameter defines the number of significant digits,
  where -1 can be used for maximum precision.

>  void jw_array_double(struct json_writer *jw, int precision, double value);
> +
> +/*
> + * Append a true value to the current array of the json_writer.
> + */
>  void jw_array_true(struct json_writer *jw);
> +
> +/*
> + * Append a false value to the current array of the json_writer.
> + */
>  void jw_array_false(struct json_writer *jw);
> +
> +/*
> + * Append a boolean value to the current array of the json_writer.
> + */
>  void jw_array_bool(struct json_writer *jw, int value);
> +
> +/*
> + * Append a null value to the current array of the json_writer.
> + */
>  void jw_array_null(struct json_writer *jw);
> +
> +/*
> + * Append a value to the current array of the json_writer, given the
> + * json_writer that represents its content.
> + */
>  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.
> + *
> + * 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.
> + */
>  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.
> + */
>  void jw_array_inline_begin_object(struct json_writer *jw);
> +
> +/*
> + * Start an array as a value in the current array.
> + */
>  void jw_array_inline_begin_array(struct json_writer *jw);
>
> +/*
> + * Return if 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);

Thanks, overall this looks good, I would drop the 'given its key' or
'given the value field' and similar  statements, as they don't provide
any additional context, but that is probably just nitpicking.

Attachment: signature.asc
Description: PGP signature