[PATCH wayland] util: Document wl_fixed_t

[Peter Hutterer]

On Fri, Nov 11, 2016 at 07:55:38AM -0800, Yong Bakos wrote:
> From: Yong Bakos <ybakos at humanoriented.com>
> 
> Add doxygen comments for wl_fixed_t and its methods.
> 
> Although wl_fixed_t can be thought of as an opaque struct, it is a typedef. As
> such, doxygen does not provide an elegant means of documenting it as both a
> 'class' with members and as a typedef. In other words, documenting it as a class
> gives us a nice doxygen page for wl_fixed_t and its related methods, but this
> leaves the typedef documentation blank in the documentation for wayland-util,
> and does not provide a link to the documentation for wl_fixed_t. Hence, this
> patch does not treat wl_fixed_t as a class/struct, resulting in the typedef
> being documented and keeping the functions listed in wayland-util, rather than a
> separate unlinked page devoted to just wl_fixed_t.
> 
> Signed-off-by: Yong Bakos <ybakos at humanoriented.com>

Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>

Cheers,
   Peter
> ---
>  src/wayland-util.h | 36 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 36 insertions(+)
> 
> diff --git a/src/wayland-util.h b/src/wayland-util.h
> index 4dba1ed..a7e4c5f 100644
> --- a/src/wayland-util.h
> +++ b/src/wayland-util.h
> @@ -511,8 +511,23 @@ wl_array_copy(struct wl_array *array, struct wl_array *source);
>  	     (const char *) pos < ((const char *) (array)->data + (array)->size); \
>  	     (pos)++)
>  
> +/**
> + * Fixed-point number
> + *
> + * A `wl_fixed_t` is a 24.8 signed fixed-point number with a sign bit, 23 bits
> + * of integer precision and 8 bits of decimal precision. Consider `wl_fixed_t`
> + * as an opaque struct with methods that facilitate conversion to and from
> + * `double` and `int` types.
> + */
>  typedef int32_t wl_fixed_t;
>  
> +/**
> + * Converts a fixed-point number to a floating-point number.
> + *
> + * \param f Fixed-point number to convert
> + *
> + * \return Floating-point representation of the fixed-point argument
> + */
>  static inline double
>  wl_fixed_to_double (wl_fixed_t f)
>  {
> @@ -526,6 +541,13 @@ wl_fixed_to_double (wl_fixed_t f)
>  	return u.d - (3LL << 43);
>  }
>  
> +/**
> + * Converts a floating-point number to a fixed-point number.
> + *
> + * \param d Floating-point number to convert
> + *
> + * \return Fixed-point representation of the floating-point argument
> + */
>  static inline wl_fixed_t
>  wl_fixed_from_double(double d)
>  {
> @@ -539,12 +561,26 @@ wl_fixed_from_double(double d)
>  	return u.i;
>  }
>  
> +/**
> + * Converts a fixed-point number to an integer.
> + *
> + * \param f Fixed-point number to convert
> + *
> + * \return Integer component of the fixed-point argument
> + */
>  static inline int
>  wl_fixed_to_int(wl_fixed_t f)
>  {
>  	return f / 256;
>  }
>  
> +/**
> + * Converts an integer to a fixed-point number.
> + *
> + * \param i Integer to convert
> + *
> + * \return Fixed-point representation of the integer argument
> + */
>  static inline wl_fixed_t
>  wl_fixed_from_int(int i)
>  {
> -- 
> 2.7.2
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
>