Re: [Qemu-ppc] [PATCH v2 3/3] util/cutils: Move function documentations to the header

[Stefano Garzarella]

On Fri, Jan 4, 2019 at 7:13 PM Philippe Mathieu-Daudé <address@hidden> wrote:
>
> Many functions have documentation before the implementation in
> cutils.c. Since we expect documentation around the prototype
> declaration in headers, move the comments in cutils.h.
>
> Signed-off-by: Philippe Mathieu-Daudé <address@hidden>
> ---
>  include/qemu/cutils.h | 224 ++++++++++++++++++++++++++++++++++++++++++
>  util/cutils.c         | 185 ----------------------------------
>  2 files changed, 224 insertions(+), 185 deletions(-)

Reviewed-by: Stefano Garzarella <address@hidden>

>
> diff --git a/include/qemu/cutils.h b/include/qemu/cutils.h
> index 644f2d75bd..f41b00ad37 100644
> --- a/include/qemu/cutils.h
> +++ b/include/qemu/cutils.h
> @@ -47,6 +47,7 @@
>   *    bytes and then add a NUL
>   */
>  void pstrcpy(char *buf, int buf_size, const char *str);
> +
>  /**
>   * strpadcpy:
>   * @buf: buffer to copy string into
> @@ -60,6 +61,7 @@ void pstrcpy(char *buf, int buf_size, const char *str);
>   * first @buf_size characters of @str, with no terminator.
>   */
>  void strpadcpy(char *buf, int buf_size, const char *str, char pad);
> +
>  /**
>   * pstrcat:
>   * @buf: buffer containing existing string
> @@ -77,6 +79,7 @@ void strpadcpy(char *buf, int buf_size, const char *str, 
> char pad);
>   * Returns: @buf.
>   */
>  char *pstrcat(char *buf, int buf_size, const char *s);
> +
>  /**
>   * strstart:
>   * @str: string to test
> @@ -94,6 +97,7 @@ char *pstrcat(char *buf, int buf_size, const char *s);
>   * Returns: true if @str starts with prefix @val, false otherwise.
>   */
>  int strstart(const char *str, const char *val, const char **ptr);
> +
>  /**
>   * stristart:
>   * @str: string to test
> @@ -110,6 +114,7 @@ int strstart(const char *str, const char *val, const char 
> **ptr);
>   *          false otherwise.
>   */
>  int stristart(const char *str, const char *val, const char **ptr);
> +
>  /**
>   * qemu_strnlen:
>   * @s: string
> @@ -126,6 +131,7 @@ int stristart(const char *str, const char *val, const 
> char **ptr);
>   * Returns: length of @s in bytes, or @max_len, whichever is smaller.
>   */
>  int qemu_strnlen(const char *s, int max_len);
> +
>  /**
>   * qemu_strsep:
>   * @input: pointer to string to parse
> @@ -147,6 +153,16 @@ int qemu_strnlen(const char *s, int max_len);
>   * Returns: the pointer originally in @input.
>   */
>  char *qemu_strsep(char **input, const char *delim);
> +
> +/**
> + * qemu_strchrnul:
> + *
> + * @s: String to parse.
> + * @c: Character to find.
> + *
> + * Searches for the first occurrence of @c in @s, and returns a pointer
> + * to the trailing null byte if none was found.
> + */
>  #ifdef HAVE_STRCHRNUL
>  static inline const char *qemu_strchrnul(const char *s, int c)
>  {
> @@ -155,27 +171,235 @@ static inline const char *qemu_strchrnul(const char 
> *s, int c)
>  #else
>  const char *qemu_strchrnul(const char *s, int c);
>  #endif
> +
>  time_t mktimegm(struct tm *tm);
>  int qemu_fdatasync(int fd);
>  int fcntl_setfl(int fd, int flag);
>  int qemu_parse_fd(const char *param);
> +
> +/**
> + * qemu_strtoi:
> + *
> + * Convert string @nptr to an integer, and store it in @result.
> + *
> + * This is a wrapper around strtol() that is harder to misuse.
> + * Semantics of @nptr, @endptr, @base match strtol() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL.  This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows @result, store INT_MAX in @result,
> + * and return -ERANGE.
> + *
> + * If the conversion underflows @result, store INT_MIN in @result,
> + * and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + */
>  int qemu_strtoi(const char *nptr, const char **endptr, int base,
>                  int *result);
> +
> +/**
> + * qemu_strtoui:
> + *
> + * Convert string @nptr to an unsigned integer, and store it in @result.
> + *
> + * This is a wrapper around strtoul() that is harder to misuse.
> + * Semantics of @nptr, @endptr, @base match strtoul() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL.  This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows @result, store UINT_MAX in @result,
> + * and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + *
> + * Note that a number with a leading minus sign gets converted without
> + * the minus sign, checked for overflow (see above), then negated (in
> + * @result's type).  This is exactly how strtoul() works.
> + */
>  int qemu_strtoui(const char *nptr, const char **endptr, int base,
>                   unsigned int *result);
> +
> +/**
> + * qemu_strtol:
> + *
> + * Convert string @nptr to a long integer, and store it in @result.
> + *
> + * This is a wrapper around strtol() that is harder to misuse.
> + * Semantics of @nptr, @endptr, @base match strtol() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL.  This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows @result, store LONG_MAX in @result,
> + * and return -ERANGE.
> + *
> + * If the conversion underflows @result, store LONG_MIN in @result,
> + * and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + */
>  int qemu_strtol(const char *nptr, const char **endptr, int base,
>                  long *result);
> +
> +/**
> + * qemu_strtoul:
> + *
> + * Convert string @nptr to an unsigned long, and store it in @result.
> + *
> + * This is a wrapper around strtoul() that is harder to misuse.
> + * Semantics of @nptr, @endptr, @base match strtoul() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL.  This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows @result, store ULONG_MAX in @result,
> + * and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + *
> + * Note that a number with a leading minus sign gets converted without
> + * the minus sign, checked for overflow (see above), then negated (in
> + * @result's type).  This is exactly how strtoul() works.
> + */
> +
>  int qemu_strtoul(const char *nptr, const char **endptr, int base,
>                   unsigned long *result);
> +
> +/**
> + * qemu_strtoi64:
> + *
> + * Convert string @nptr to an int64_t.
> + *
> + * Works like qemu_strtol(), except it stores INT64_MAX on overflow,
> + * and INT_MIN on underflow.
> + */
>  int qemu_strtoi64(const char *nptr, const char **endptr, int base,
>                    int64_t *result);
> +
> +/**
> + * qemu_strtou64:
> + *
> + * Convert string @nptr to an uint64_t.
> + *
> + * Works like qemu_strtoul(), except it stores UINT64_MAX on overflow.
> + */
>  int qemu_strtou64(const char *nptr, const char **endptr, int base,
>                    uint64_t *result);
> +
> +/**
> + * qemu_strtod:
> + *
> + * Convert string @nptr to a double.
> + *
> + * This is a wrapper around strtod() that is harder to misuse.
> + * Semantics of @nptr and @endptr match strtod() with differences
> + * noted below.
> + *
> + * @nptr may be null, and no conversion is performed then.
> + *
> + * If no conversion is performed, store @nptr in address@hidden and return
> + * -EINVAL.
> + *
> + * If @endptr is null, and the string isn't fully converted, return
> + * -EINVAL. This is the case when the pointer that would be stored in
> + * a non-null @endptr points to a character other than '\0'.
> + *
> + * If the conversion overflows, store +/-HUGE_VAL in @result, depending
> + * on the sign, and return -ERANGE.
> + *
> + * If the conversion underflows, store +/-0.0 in @result, depending on the
> + * sign, and return -ERANGE.
> + *
> + * Else store the converted value in @result, and return zero.
> + */
>  int qemu_strtod(const char *nptr, const char **endptr, double *result);
> +
> +/**
> + * qemu_strtod_finite:
> + *
> + * Convert string @nptr to a finite double.
> + *
> + * Works like qemu_strtod(), except that "NaN" and "inf" are rejected
> + * with -EINVAL and no conversion is performed.
> + */
>  int qemu_strtod_finite(const char *nptr, const char **endptr, double 
> *result);
>
> +/**
> + * parse_uint:
> + *
> + * @s: String to parse
> + * @value: Destination for parsed integer value
> + * @endptr: Destination for pointer to first character not consumed
> + * @base: integer base, between 2 and 36 inclusive, or 0
> + *
> + * Parse unsigned integer
> + *
> + * Parsed syntax is like strtoull()'s: arbitrary whitespace, a single 
> optional
> + * '+' or '-', an optional "0x" if @base is 0 or 16, one or more digits.
> + *
> + * If @s is null, or @base is invalid, or @s doesn't start with an
> + * integer in the syntax above, set address@hidden to 0, address@hidden to 
> @s, and
> + * return -EINVAL.
> + *
> + * Set address@hidden to point right beyond the parsed integer (even if the 
> integer
> + * overflows or is negative, all digits will be parsed and address@hidden 
> will
> + * point right beyond them).
> + *
> + * If the integer is negative, set address@hidden to 0, and return -ERANGE.
> + *
> + * If the integer overflows unsigned long long, set address@hidden to
> + * ULLONG_MAX, and return -ERANGE.
> + *
> + * Else, set address@hidden to the parsed integer, and return 0.
> + */
>  int parse_uint(const char *s, unsigned long long *value, char **endptr,
>                 int base);
> +
> +/**
> + * parse_uint_full:
> + *
> + * @s: String to parse
> + * @value: Destination for parsed integer value
> + * @base: integer base, between 2 and 36 inclusive, or 0
> + *
> + * Parse unsigned integer from entire string
> + *
> + * Have the same behavior of parse_uint(), but with an additional check
> + * for additional data after the parsed number. If extra characters are 
> present
> + * after the parsed number, the function will return -EINVAL, and 
> address@hidden will
> + * be set to 0.
> + */
>  int parse_uint_full(const char *s, unsigned long long *value, int base);
>
>  int qemu_strtosz(const char *nptr, const char **end, uint64_t *result);
> diff --git a/util/cutils.c b/util/cutils.c
> index a8a3a3ba3b..a4c8858712 100644
> --- a/util/cutils.c
> +++ b/util/cutils.c
> @@ -296,30 +296,6 @@ static int check_strtox_error(const char *nptr, char *ep,
>      return -libc_errno;
>  }
>
> -/**
> - * Convert string @nptr to an integer, and store it in @result.
> - *
> - * This is a wrapper around strtol() that is harder to misuse.
> - * Semantics of @nptr, @endptr, @base match strtol() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL.  This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows @result, store INT_MAX in @result,
> - * and return -ERANGE.
> - *
> - * If the conversion underflows @result, store INT_MIN in @result,
> - * and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - */
>  int qemu_strtoi(const char *nptr, const char **endptr, int base,
>                  int *result)
>  {
> @@ -348,31 +324,6 @@ int qemu_strtoi(const char *nptr, const char **endptr, 
> int base,
>      return check_strtox_error(nptr, ep, endptr, errno);
>  }
>
> -/**
> - * Convert string @nptr to an unsigned integer, and store it in @result.
> - *
> - * This is a wrapper around strtoul() that is harder to misuse.
> - * Semantics of @nptr, @endptr, @base match strtoul() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL.  This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows @result, store UINT_MAX in @result,
> - * and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - *
> - * Note that a number with a leading minus sign gets converted without
> - * the minus sign, checked for overflow (see above), then negated (in
> - * @result's type).  This is exactly how strtoul() works.
> - */
>  int qemu_strtoui(const char *nptr, const char **endptr, int base,
>                   unsigned int *result)
>  {
> @@ -407,30 +358,6 @@ int qemu_strtoui(const char *nptr, const char **endptr, 
> int base,
>      return check_strtox_error(nptr, ep, endptr, errno);
>  }
>
> -/**
> - * Convert string @nptr to a long integer, and store it in @result.
> - *
> - * This is a wrapper around strtol() that is harder to misuse.
> - * Semantics of @nptr, @endptr, @base match strtol() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL.  This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows @result, store LONG_MAX in @result,
> - * and return -ERANGE.
> - *
> - * If the conversion underflows @result, store LONG_MIN in @result,
> - * and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - */
>  int qemu_strtol(const char *nptr, const char **endptr, int base,
>                  long *result)
>  {
> @@ -449,31 +376,6 @@ int qemu_strtol(const char *nptr, const char **endptr, 
> int base,
>      return check_strtox_error(nptr, ep, endptr, errno);
>  }
>
> -/**
> - * Convert string @nptr to an unsigned long, and store it in @result.
> - *
> - * This is a wrapper around strtoul() that is harder to misuse.
> - * Semantics of @nptr, @endptr, @base match strtoul() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL.  This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows @result, store ULONG_MAX in @result,
> - * and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - *
> - * Note that a number with a leading minus sign gets converted without
> - * the minus sign, checked for overflow (see above), then negated (in
> - * @result's type).  This is exactly how strtoul() works.
> - */
>  int qemu_strtoul(const char *nptr, const char **endptr, int base,
>                   unsigned long *result)
>  {
> @@ -496,12 +398,6 @@ int qemu_strtoul(const char *nptr, const char **endptr, 
> int base,
>      return check_strtox_error(nptr, ep, endptr, errno);
>  }
>
> -/**
> - * Convert string @nptr to an int64_t.
> - *
> - * Works like qemu_strtol(), except it stores INT64_MAX on overflow,
> - * and INT_MIN on underflow.
> - */
>  int qemu_strtoi64(const char *nptr, const char **endptr, int base,
>                   int64_t *result)
>  {
> @@ -521,11 +417,6 @@ int qemu_strtoi64(const char *nptr, const char **endptr, 
> int base,
>      return check_strtox_error(nptr, ep, endptr, errno);
>  }
>
> -/**
> - * Convert string @nptr to an uint64_t.
> - *
> - * Works like qemu_strtoul(), except it stores UINT64_MAX on overflow.
> - */
>  int qemu_strtou64(const char *nptr, const char **endptr, int base,
>                    uint64_t *result)
>  {
> @@ -549,30 +440,6 @@ int qemu_strtou64(const char *nptr, const char **endptr, 
> int base,
>      return check_strtox_error(nptr, ep, endptr, errno);
>  }
>
> -/**
> - * Convert string @nptr to a double.
> -  *
> - * This is a wrapper around strtod() that is harder to misuse.
> - * Semantics of @nptr and @endptr match strtod() with differences
> - * noted below.
> - *
> - * @nptr may be null, and no conversion is performed then.
> - *
> - * If no conversion is performed, store @nptr in address@hidden and return
> - * -EINVAL.
> - *
> - * If @endptr is null, and the string isn't fully converted, return
> - * -EINVAL. This is the case when the pointer that would be stored in
> - * a non-null @endptr points to a character other than '\0'.
> - *
> - * If the conversion overflows, store +/-HUGE_VAL in @result, depending
> - * on the sign, and return -ERANGE.
> - *
> - * If the conversion underflows, store +/-0.0 in @result, depending on the
> - * sign, and return -ERANGE.
> - *
> - * Else store the converted value in @result, and return zero.
> - */
>  int qemu_strtod(const char *nptr, const char **endptr, double *result)
>  {
>      char *ep;
> @@ -589,12 +456,6 @@ int qemu_strtod(const char *nptr, const char **endptr, 
> double *result)
>      return check_strtox_error(nptr, ep, endptr, errno);
>  }
>
> -/**
> - * Convert string @nptr to a finite double.
> - *
> - * Works like qemu_strtod(), except that "NaN" and "inf" are rejected
> - * with -EINVAL and no conversion is performed.
> - */
>  int qemu_strtod_finite(const char *nptr, const char **endptr, double *result)
>  {
>      double tmp;
> @@ -614,10 +475,6 @@ int qemu_strtod_finite(const char *nptr, const char 
> **endptr, double *result)
>      return ret;
>  }
>
> -/**
> - * Searches for the first occurrence of 'c' in 's', and returns a pointer
> - * to the trailing null byte if none was found.
> - */
>  #ifndef HAVE_STRCHRNUL
>  const char *qemu_strchrnul(const char *s, int c)
>  {
> @@ -629,34 +486,6 @@ const char *qemu_strchrnul(const char *s, int c)
>  }
>  #endif
>
> -/**
> - * parse_uint:
> - *
> - * @s: String to parse
> - * @value: Destination for parsed integer value
> - * @endptr: Destination for pointer to first character not consumed
> - * @base: integer base, between 2 and 36 inclusive, or 0
> - *
> - * Parse unsigned integer
> - *
> - * Parsed syntax is like strtoull()'s: arbitrary whitespace, a single 
> optional
> - * '+' or '-', an optional "0x" if @base is 0 or 16, one or more digits.
> - *
> - * If @s is null, or @base is invalid, or @s doesn't start with an
> - * integer in the syntax above, set address@hidden to 0, address@hidden to 
> @s, and
> - * return -EINVAL.
> - *
> - * Set address@hidden to point right beyond the parsed integer (even if the 
> integer
> - * overflows or is negative, all digits will be parsed and address@hidden 
> will
> - * point right beyond them).
> - *
> - * If the integer is negative, set address@hidden to 0, and return -ERANGE.
> - *
> - * If the integer overflows unsigned long long, set address@hidden to
> - * ULLONG_MAX, and return -ERANGE.
> - *
> - * Else, set address@hidden to the parsed integer, and return 0.
> - */
>  int parse_uint(const char *s, unsigned long long *value, char **endptr,
>                 int base)
>  {
> @@ -698,20 +527,6 @@ out:
>      return r;
>  }
>
> -/**
> - * parse_uint_full:
> - *
> - * @s: String to parse
> - * @value: Destination for parsed integer value
> - * @base: integer base, between 2 and 36 inclusive, or 0
> - *
> - * Parse unsigned integer from entire string
> - *
> - * Have the same behavior of parse_uint(), but with an additional check
> - * for additional data after the parsed number. If extra characters are 
> present
> - * after the parsed number, the function will return -EINVAL, and 
> address@hidden will
> - * be set to 0.
> - */
>  int parse_uint_full(const char *s, unsigned long long *value, int base)
>  {
>      char *endp;
> --
> 2.17.2
>