[PATCH wayland] util: Document wl_fixed_t
Yong Bakos
junk at humanoriented.com
Fri Nov 11 15:55:38 UTC 2016
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>
---
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
More information about the wayland-devel
mailing list