[PATCH wayland] util: Document wl_fixed_t
Peter Hutterer
peter.hutterer at who-t.net
Sun Nov 13 22:29:48 UTC 2016
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
>
More information about the wayland-devel
mailing list