From: Yong Bakos <[email protected]> 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 <[email protected]> --- 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 [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
