Tweak doc comments.

rp2040-hal/src/rom_data.rs

@@ -238,92 +238,115 @@ macro_rules! float_funcs {
 }
 
 float_funcs! {
-    /// Return a + b.
+    /// Returns a function that will calculate `a + b`
     0x00 fadd(a: f32, b: f32) -> f32;
-    /// Return a - b.
+    /// Returns a function that will calculate `a - b`
     0x04 fsub(a: f32, b: f32) -> f32;
-    /// Return a * b.
+    /// Returns a function that will calculate `a * b`
     0x08 fmul(a: f32, b: f32) -> f32;
-    /// Return a / b.
+    /// Returns a function that will calculate `a / b`
     0x0c fdiv(a: f32, b: f32) -> f32;
-    /// Return the square root of v or -INFINITY if v is negative.
+    /// Returns a function that will calculate `sqrt(v)` (or return -Infinity if v is negative)
     0x18 fsqrt(v: f32) -> f32;
-    /// Convert a float to a signed integer, rounding towards -INFINITY, and clamping the result
+    /// Returns a function that will convert an f32 to a signed integer,
-    /// to lie within the range -0x80000000 to 0x7FFFFFFF.
+    /// rounding towards -Infinity, and clamping the result to lie within the
+    /// range `-0x80000000` to `0x7FFFFFFF`
     0x1c float_to_int(v: f32) -> i32;
-    /// Convert a float to a signed fixed point integer reprsentation where n specifies the
+    /// Returns a function that will convert an f32 to an signed fixed point
-    /// position of the binary point in the resulting fixed point representation. e.g.
+    /// integer representation where n specifies the position of the binary
-    /// float_to_fix(0.5, 16) == 0x8000. This method rounds towards -INFINITY, and clamps
+    /// point in the resulting fixed point representation, e.g.
-    /// the resulting integer to lie within the range -800000000 to 0x7FFFFFFF.
+    /// `f(0.5f, 16) == 0x8000`. This method rounds towards -Infinity,
+    /// and clamps the resulting integer to lie within the range `0x00000000` to
+    /// `0xFFFFFFFF`
     0x20 float_to_fix(v: f32, n: i32) -> i32;
-    /// Convert a float to an unsigned integer, rounding towards -INFINITY, and clamping the result
+    /// Returns a function that will convert an f32 to an unsigned integer,
-    /// to lie within the range 0x00000000 to 0xFFFFFFFF
+    /// rounding towards -Infinity, and clamping the result to lie within the
+    /// range `0x00000000` to `0xFFFFFFFF`
     0x24 float_to_uint(v: f32) -> u32;
-    /// Convert a float to an unsigned fixed point integer representation where n specifies the
+    /// Returns a function that will convert an f32 to an unsigned fixed point
-    /// position of the binary point in the resulting fixed point representation, e.g.
+    /// integer representation where n specifies the position of the binary
-    /// float_to_ufix(0.5f, 16) == 0x8000. This method rounds towards -Infinity, and clamps the
+    /// point in the resulting fixed point representation, e.g.
-    /// resulting integer to lie within the range 0x00000000 to 0xFFFFFFFF.
+    /// `f(0.5f, 16) == 0x8000`. This method rounds towards -Infinity,
+    /// and clamps the resulting integer to lie within the range `0x00000000` to
+    /// `0xFFFFFFFF`
     0x28 float_to_ufix(v: f32, n: i32) -> u32;
-    /// Convert a signed integer to the nearest float value, rounding to even on tie.
+    /// Returns a function that will convert a signed integer to the nearest
+    /// f32 value, rounding to even on tie
     0x2c int_to_float(v: i32) -> f32;
-    /// Convert a signed fixed point integer representation to the nearest float value, rounding
+    /// Returns a function that will convert a signed fixed point integer
-    /// to even on tie. n specifies the position of the binary point in fixed point, so
+    /// representation to the nearest f32 value, rounding to even on tie. `n`
-    /// f = nearest(v/2^n).
+    /// specifies the position of the binary point in fixed point, so `f =
+    /// nearest(v/(2^n))`
     0x30 fix_to_float(v: i32, n: i32) -> f32;
-    /// Convert an unsigned integer to the nearest float value, rounding to even on tie.
+    /// Returns a function that will convert an unsigned integer to the nearest
+    /// f32 value, rounding to even on tie
     0x34 uint_to_float(v: u32) -> f32;
-    /// Convert a unsigned fixed point integer representation to the nearest float value, rounding
+    /// Returns a function that will convert an unsigned fixed point integer
-    /// to even on tie. n specifies the position of the binary point in fixed point, so
+    /// representation to the nearest f32 value, rounding to even on tie. `n`
-    /// f = nearest(v/2^n).
+    /// specifies the position of the binary point in fixed point, so `f =
+    /// nearest(v/(2^n))`
     0x38 ufix_to_float(v: u32, n: i32) -> f32;
-    /// Return the cosine of angle. angle is in radians, and must be in the range -128 to 128.
+    /// Returns a function that will calculate the cosine of `angle`. The value
+    /// of `angle` is in radians, and must be in the range `-1024` to `1024`
     0x3c fcos(angle: f32) -> f32;
-    /// Return the sine of angle. angle is in radians, and must be in the range -128 to 128.
+    /// Returns a function that will calculate the sine of `angle`. The value of
+    /// `angle` is in radians, and must be in the range `-1024` to `1024`
     0x40 fsin(angle: f32) -> f32;
-    /// Return the tangent of angle. angle is in radians, and must be in the range -128 to 128.
+    /// Returns a function that will calculate the tangent of `angle`. The value
+    /// of `angle` is in radians, and must be in the range `-1024` to `1024`
     0x44 ftan(angle: f32) -> f32;
-    /// Return the exponential value of v, i.e. so e^v.
+    /// Returns a function that will calculate the exponential value of `v`,
+    /// i.e. `e ** v`
     0x4c fexp(v: f32) -> f32;
-    /// Return the natural logarithm of v. If v <= 0 return -Infinity.
+    /// Returns a function that will calculate the natural logarithm of `v`. If `v <= 0` return -Infinity
     0x50 fln(v: f32) -> f32;
-    /// Compares two floating point numbers, returning:
+    /// Returns a function that will compare two floating point numbers, returning:
-    ///   * 0 if a == b
+    ///     • 0 if a == b
-    ///   * -1 if a < b
+    ///     • -1 if a < b
-    ///   * 1 if a > b
+    ///     • 1 if a > b
     0x54 fcmp(a: f32, b: f32) -> i32;
-    /// Computes the arc tangent of y/x using the signs of arguments to determine the correct quadrant.
+    /// Returns a function that will compute the arc tangent of `y/x` using the
+    /// signs of arguments to determine the correct quadrant
     0x58 fatan2(y: f32, x: f32) -> f32;
-    /// Convert a signed 64-bit integer to the nearest float value, rounding to even on tie.
+    /// Returns a function that will convert a signed 64-bit integer to the
+    /// nearest f32 value, rounding to even on tie
     0x5c int64_to_float(v: i64) -> f32;
-    /// Convert a signed fixed point integer representation to the nearest float value, rounding
+    /// Returns a function that will convert a signed fixed point 64-bit integer
-    /// to even on tie. n specifies the position of the binary point in fixed point, so
+    /// representation to the nearest f32 value, rounding to even on tie. `n`
-    /// f = nearest(v/2^n).
+    /// specifies the position of the binary point in fixed point, so `f =
+    /// nearest(v/(2^n))`
     0x60 fix64_to_float(v: i64, n: i32) -> f32;
-    /// Convert an unsigned 64-bit integer to the nearest float value, rounding to even on tie.
+    /// Returns a function that will convert an unsigned 64-bit integer to the
+    /// nearest f32 value, rounding to even on tie
     0x64 uint64_to_float(v: u64) -> f32;
-    /// Convert an unsigned fixed point integer representation to the nearest float value, rounding
+    /// Returns a function that will convert an unsigned fixed point 64-bit
-    /// to even on tie. n specifies the position of the binary point in fixed point, so
+    /// integer representation to the nearest f32 value, rounding to even on
-    /// f = nearest(v/2^n).
+    /// tie. `n` specifies the position of the binary point in fixed point, so
+    /// `f = nearest(v/(2^n))`
     0x68 ufix64_to_float(v: u64, n: i32) -> f32;
-    /// Convert a float to a signed 64-bit integer, rounding towards -Infinity, and clamping
+    /// Convert an f32 to a signed 64-bit integer, rounding towards -Infinity,
-    /// the result to lie within the range -0x8000000000000000 to 0x7FFFFFFFFFFFFFFF
+    /// and clamping the result to lie within the range `-0x8000000000000000` to
+    /// `0x7FFFFFFFFFFFFFFF`
     0x6c float_to_int64(v: f32) -> i64;
-    /// Convert a float to a signed fixed point 64-bit integer representation where n
+    /// Returns a function that will convert a f32 to a signed fixed point
-    /// specifies the position of the binary point in the resulting fixed point representation -
+    /// 64-bit integer representation where n specifies the position of the
-    /// e.g. _float2fix(0.5f, 16) == 0x8000. This method rounds towards -Infinity, and
+    /// binary point in the resulting fixed point representation - e.g. `f(0.5f,
-    /// clamps the resulting integer to lie within the range -0x8000000000000000 to
+    /// 16) == 0x8000`. This method rounds towards -Infinity, and clamps the
-    /// 0x7FFFFFFFFFFFFFF
+    /// resulting integer to lie within the range `-0x8000000000000000` to
+    /// `0x7FFFFFFFFFFFFFFF`
     0x70 float_to_fix64(v: f32, n: i32) -> f32;
-    /// Convert a float to an unsigned 64-bit integer, rounding towards -Infinity, and
+    /// Returns a function that will convert an f32 to an unsigned 64-bit
-    /// clamping the result to lie within the range 0x0000000000000000 to 0xFFFFFFFFFFFFFFFF
+    /// integer, rounding towards -Infinity, and clamping the result to lie
+    /// within the range `0x0000000000000000` to `0xFFFFFFFFFFFFFFFF`
     0x74 float_to_uint64(v: f32) -> u64;
-    /// Convert a float to an unsigned fixed point 64-bit integer representation where n
+    /// Returns a function that will convert an f32 to an unsigned fixed point
-    /// specifies the position of the binary point in the resulting fixed point representation,
+    /// 64-bit integer representation where n specifies the position of the
-    /// e.g. _float2ufix(0.5f, 16) == 0x8000. This method rounds towards -Infinity, and
+    /// binary point in the resulting fixed point representation, e.g. `f(0.5f,
-    /// clamps the resulting integer to lie within the range 0x0000000000000000 to
+    /// 16) == 0x8000`. This method rounds towards -Infinity, and clamps the
-    /// 0xFFFFFFFFFFFFFFFF
+    /// resulting integer to lie within the range `0x0000000000000000` to
-    /// 0x78 float_to_ufix64(v: f32, n: i32) -> u64;
+    /// `0xFFFFFFFFFFFFFFFF`
-    /// Converts a float to a double.
+    0x78 float_to_ufix64(v: f32, n: i32) -> u64;
+    /// Converts an f32 to an f64.
     0x7c float_to_double(v: f32) -> f64;
 }
 
@@ -356,83 +379,114 @@ macro_rules! double_funcs {
 }
 
 double_funcs! {
-    /// Return a + b
+    /// Returns a function that will calculate `a + b`
     0x00 dadd(a: f64, b: f64) -> f64;
-    /// Return a - b
+    /// Returns a function that will calculate `a - b`
     0x04 dsub(a: f64, b: f64) -> f64;
-    /// Return a * b
+    /// Returns a function that will calculate `a * b`
     0x08 dmul(a: f64, b: f64) -> f64;
-    /// Return a / b
+    /// Returns a function that will calculate `a / b`
     0x0c ddiv(a: f64, b: f64) -> f64;
-    /// Return sqrt(v) or -Infinity if v is negative
+    /// Returns a function that will calculate `sqrt(v)` (or return -Infinity if v is negative)
     0x18 dsqrt(v: f64) -> f64;
-    /// Convert a double to a signed integer, rounding towards -Infinity, and clamping the result to lie
+    /// Returns a function that will convert an f64 to a signed integer,
-    /// within the range -0x80000000 to 0x7FFFFFFF
+    /// rounding towards -Infinity, and clamping the result to lie within the
+    /// range `-0x80000000` to `0x7FFFFFFF`
     0x1c double_to_int(v: f64) -> i32;
-    /// Convert a double to an unsigned fixed point integer representation where n specifies the
+    /// Returns a function that will convert an f64 to an signed fixed point
-    /// position of the binary point in the resulting fixed point representation, e.g. _double2ufix(0.5f,
+    /// integer representation where n specifies the position of the binary
-    /// 16) == 0x8000. This method rounds towards -Infinity, and clamps the resulting integer to lie
+    /// point in the resulting fixed point representation, e.g.
-    /// within the range 0x00000000 to 0xFFFFFFFF
+    /// `f(0.5f, 16) == 0x8000`. This method rounds towards -Infinity,
+    /// and clamps the resulting integer to lie within the range `0x00000000` to
+    /// `0xFFFFFFFF`
     0x20 double_to_fix(v: f64, n: i32) -> i32;
-    /// Convert a double to an unsigned integer, rounding towards -Infinity, and clamping the result
+    /// Returns a function that will convert an f64 to an unsigned integer,
-    /// to lie within the range 0x00000000 to 0xFFFFFFFF    0x24 double_to_uint(v: f64) -> u32;
+    /// rounding towards -Infinity, and clamping the result to lie within the
+    /// range `0x00000000` to `0xFFFFFFFF`
+    0x24 double_to_uint(v: f64) -> u32;
+    /// Returns a function that will convert an f64 to an unsigned fixed point
+    /// integer representation where n specifies the position of the binary
+    /// point in the resulting fixed point representation, e.g.
+    /// `f(0.5f, 16) == 0x8000`. This method rounds towards -Infinity,
+    /// and clamps the resulting integer to lie within the range `0x00000000` to
+    /// `0xFFFFFFFF`
     0x28 double_to_ufix(v: f64, n: i32) -> u32;
-    /// Convert a signed integer to the nearest double value, rounding to even on tie
+    /// Returns a function that will convert a signed integer to the nearest
+    /// double value, rounding to even on tie
     0x2c int_to_double(v: i32) -> f64;
-    /// Convert a signed fixed point integer representation to the nearest double value, rounding to
+    /// Returns a function that will convert a signed fixed point integer
-    /// even on tie. n specifies the position of the binary point in fixed point, so f = nearest(v/(2^n))
+    /// representation to the nearest double value, rounding to even on tie. `n`
+    /// specifies the position of the binary point in fixed point, so `f =
+    /// nearest(v/(2^n))`
     0x30 fix_to_double(v: i32, n: i32) -> f64;
-    /// Convert an unsigned integer to the nearest double value, rounding to even on tie
+    /// Returns a function that will convert an unsigned integer to the nearest
+    /// double value, rounding to even on tie
     0x34 uint_to_double(v: u32) -> f64;
-    /// Convert an unsigned fixed point integer representation to the nearest double value, rounding
+    /// Returns a function that will convert an unsigned fixed point integer
-    /// to even on tie. n specifies the position of the binary point in fixed point, so
+    /// representation to the nearest double value, rounding to even on tie. `n`
-    /// f = nearest(v/(2^n))
+    /// specifies the position of the binary point in fixed point, so f =
+    /// nearest(v/(2^n))
     0x38 ufix_to_double(v: u32, n: i32) -> f64;
-    /// Return the cosine of angle. angle is in radians, and must be in the range -1024 to 1024
+    /// Returns a function that will calculate the cosine of `angle`. The value
+    /// of `angle` is in radians, and must be in the range `-1024` to `1024`
     0x3c dcos(angle: f64) -> f64;
-    /// Return the sine of angle. angle is in radians, and must be in the range -1024 to 1024
+    /// Returns a function that will calculate the sine of `angle`. The value of
+    /// `angle` is in radians, and must be in the range -1024 to 1024
     0x40 dsin(angle: f64) -> f64;
-    /// Return the tangent of angle. angle is in radians, and must be in the range -1024 to 1024
+    /// Returns a function that will calculate the tangent of `angle`. The value
+    /// of `angle` is in radians, and must be in the range `-1024` to `1024`
     0x44 dtan(angle: f64) -> f64;
-    /// Return the exponential value of v, i.e. so
+    /// Returns a function that will calculate the exponential value of `v`,
+    /// i.e. `e ** v`
     0x4c dexp(v: f64) -> f64;
-    /// Return the natural logarithm of v. If v <= 0 return -Infinity
+    /// Returns a function that will calculate the natural logarithm of v. If v <= 0 return -Infinity
     0x50 dln(v: f64) -> f64;
-    /// Compares two floating point numbers, returning:
+    /// Returns a function that will compare two floating point numbers, returning:
     ///     • 0 if a == b
     ///     • -1 if a < b
     ///     • 1 if a > b
     0x54 dcmp(a: f64, b: f64) -> i32;
-    /// Computes the arc tangent of y/x using the signs of arguments to determine the correct
+    /// Returns a function that will compute the arc tangent of `y/x` using the
-    /// quadrant
+    /// signs of arguments to determine the correct quadrant
     0x58 datan2(y: f64, x: f64) -> f64;
-    /// Convert a signed 64-bit integer to the nearest double value, rounding to even on tie
+    /// Returns a function that will convert a signed 64-bit integer to the
+    /// nearest double value, rounding to even on tie
     0x5c int64_to_double(v: i64) -> f64;
-    /// Convert a signed fixed point 64-bit integer representation to the nearest double value,
+    /// Returns a function that will convert a signed fixed point 64-bit integer
-    /// rounding to even on tie. n specifies the position of the binary point in fixed point, so
+    /// representation to the nearest double value, rounding to even on tie. `n`
-    /// f = nearest(v/(2^n))
+    /// specifies the position of the binary point in fixed point, so `f =
+    /// nearest(v/(2^n))`
     0x60 fix64_to_doubl(v: i64, n: i32) -> f64;
-    /// Convert an unsigned 64-bit integer to the nearest double value, rounding to even on tie
+    /// Returns a function that will convert an unsigned 64-bit integer to the
+    /// nearest double value, rounding to even on tie
     0x64 uint64_to_double(v: u64) -> f64;
-    /// Convert an unsigned fixed point 64-bit integer representation to the nearest double value,
+    /// Returns a function that will convert an unsigned fixed point 64-bit
-    /// rounding to even on tie. n specifies the position of the binary point in fixed point, so
+    /// integer representation to the nearest double value, rounding to even on
-    /// f = nearest(v/(2^n))
+    /// tie. `n` specifies the position of the binary point in fixed point, so
+    /// `f = nearest(v/(2^n))`
     0x68 ufix64_to_double(v: u64, n: i32) -> f64;
-    /// Convert a double to a signed 64-bit integer, rounding towards -Infinity, and
+    /// Convert an f64 to a signed 64-bit integer, rounding towards -Infinity,
+    /// and clamping the result to lie within the range `-0x8000000000000000` to
+    /// `0x7FFFFFFFFFFFFFFF`
     0x6c double_to_int64(v: f64) -> i64;
-    /// Convert a double to a signed fixed point 64-bit integer representation where n specifies the
+    /// Returns a function that will convert an f64 to a signed fixed point
-    /// position of the binary point in the resulting fixed point representation - e.g. _double2fix(0.5f,
+    /// 64-bit integer representation where n specifies the position of the
-    /// 16) == 0x8000. This method rounds towards -Infinity, and clamps the resulting integer to lie
+    /// binary point in the resulting fixed point representation - e.g. `f(0.5f,
-    /// within the range -0x8000000000000000 to 0x7FFFFFFFFFFFFFFF
+    /// 16) == 0x8000`. This method rounds towards -Infinity, and clamps the
+    /// resulting integer to lie within the range `-0x8000000000000000` to
+    /// `0x7FFFFFFFFFFFFFFF`
     0x70 double_to_fix64(v: f64, n: i32) -> i64;
-    /// Convert a double to an unsigned 64-bit integer, rounding towards -Infinity, and clamping the
+    /// Returns a function that will convert an f64 to an unsigned 64-bit
-    /// result to lie within the range 0x0000000000000000 to 0xFFFFFFFFFFFFFFFF
+    /// integer, rounding towards -Infinity, and clamping the result to lie
+    /// within the range `0x0000000000000000` to `0xFFFFFFFFFFFFFFFF`
     0x74 double_to_uint64(v: f64) -> u64;
-    /// Convert a double to an unsigned fixed point 64-bit integer representation where n specifies
+    /// Returns a function that will convert an f64 to an unsigned fixed point
-    /// the position of the binary point in the resulting fixed point representation, e.g.
+    /// 64-bit integer representation where n specifies the position of the
-    /// _double2ufix(0.5f, 16) == 0x8000. This method rounds towards -Infinity, and clamps the
+    /// binary point in the resulting fixed point representation, e.g. `f(0.5f,
-    /// resulting integer to lie within the range 0x0000000000000000 to 0xFFFFFFFFFFFFFFFF
+    /// 16) == 0x8000`. This method rounds towards -Infinity, and clamps the
+    /// resulting integer to lie within the range `0x0000000000000000` to
+    /// `0xFFFFFFFFFFFFFFFF`
     0x78 double_to_ufix64(v: f64, n: i32) -> u64;
-    /// Converts a double to a float
+    /// Returns a function that will convert an f64 to a f32
     0x7c double_to_float(v: f64) -> f32;
 }