Improve documentation for `float` and `int` types (#4725)

2 files changed, 22 insertions, 20 deletions

diff --git a/crates/typst/src/foundations/float.rs b/crates/typst/src/foundations/float.rs
index ee442a29..d346c329 100644
--- a/crates/typst/src/foundations/float.rs
+++ b/crates/typst/src/foundations/float.rs
@@ -27,10 +27,12 @@ impl f64 {
     /// Converts a value to a float.
     ///
     /// - Booleans are converted to `0.0` or `1.0`.
-    /// - Integers are converted to the closest 64-bit float.
+    /// - Integers are converted to the closest 64-bit float. For integers with
+    ///   absolute value less than `{calc.pow(2, 53)}`, this conversion is
+    ///   exact.
     /// - Ratios are divided by 100%.
-    /// - Strings are parsed in base 10 to the closest 64-bit float.
-    ///   Exponential notation is supported.
+    /// - Strings are parsed in base 10 to the closest 64-bit float. Exponential
+    ///   notation is supported.
     ///
     /// ```example
     /// #float(false) \
@@ -65,8 +67,8 @@ impl f64 {
 
     /// Checks if a float is infinite.
     ///
-    /// For floats, there is positive and negative infinity. This function
-    /// returns `true` if the float is either positive or negative infinity.
+    /// Floats can represent positive infinity and negative infinity. This
+    /// function returns `{true}` if the float is an infinity.
     ///
     /// ```example
     /// #float.is-infinite(0) \
@@ -82,13 +84,13 @@ impl f64 {
     ///
     /// - If the number is positive (including `{+0.0}`), returns `{1.0}`.
     /// - If the number is negative (including `{-0.0}`), returns `{-1.0}`.
-    /// - If the number is [`{calc.nan}`]($calc.nan), returns
-    ///   [`{calc.nan}`]($calc.nan).
+    /// - If the number is `{calc.nan}`, returns `{calc.nan}`.
     ///
     /// ```example
     /// #(5.0).signum() \
     /// #(-5.0).signum() \
     /// #(0.0).signum() \
+    /// #calc.nan.signum()
     /// ```
     #[func]
     pub fn signum(self) -> f64 {
diff --git a/crates/typst/src/foundations/int.rs b/crates/typst/src/foundations/int.rs
index eb924649..4c1335fc 100644
--- a/crates/typst/src/foundations/int.rs
+++ b/crates/typst/src/foundations/int.rs
@@ -62,7 +62,7 @@ impl i64 {
     /// ```example
     /// #(5).signum() \
     /// #(-5).signum() \
-    /// #(0).signum() \
+    /// #(0).signum()
     /// ```
     #[func]
     pub fn signum(self) -> i64 {
@@ -75,7 +75,7 @@ impl i64 {
     /// integer of 64 bits.
     ///
     /// ```example
-    /// #4.bit-not()
+    /// #4.bit-not() \
     /// #(-1).bit-not()
     /// ```
     #[func(title = "Bitwise NOT")]
@@ -141,7 +141,7 @@ impl i64 {
     /// fit in a 64-bit integer.
     ///
     /// ```example
-    /// #33.bit-lshift(2)
+    /// #33.bit-lshift(2) \
     /// #(-1).bit-lshift(3)
     /// ```
     #[func(title = "Bitwise Left Shift")]
@@ -162,8 +162,8 @@ impl i64 {
     /// integer of 64 bits.
     ///
     /// ```example
-    /// #64.bit-rshift(2)
-    /// #(-8).bit-rshift(2)
+    /// #64.bit-rshift(2) \
+    /// #(-8).bit-rshift(2) \
     /// #(-8).bit-rshift(2, logical: true)
     /// ```
     #[func(title = "Bitwise Right Shift")]
@@ -172,17 +172,17 @@ impl i64 {
         /// The amount of bits to shift. Must not be negative.
         ///
         /// Shifts larger than 63 are allowed and will cause the return value to
-        /// saturate. For non-negative numbers, the return value saturates at `0`,
-        /// while, for negative numbers, it saturates at `-1` if `logical` is set
-        /// to `false`, or `0` if it is `true`. This behavior is consistent with
-        /// just applying this operation multiple times. Therefore, the shift will
-        /// always succeed.
+        /// saturate. For non-negative numbers, the return value saturates at
+        /// `{0}`, while, for negative numbers, it saturates at `{-1}` if
+        /// `logical` is set to `{false}`, or `{0}` if it is `{true}`. This
+        /// behavior is consistent with just applying this operation multiple
+        /// times. Therefore, the shift will always succeed.
         shift: u32,
         /// Toggles whether a logical (unsigned) right shift should be performed
         /// instead of arithmetic right shift.
-        /// If this is `true`, negative operands will not preserve their sign bit,
-        /// and bits which appear to the left after the shift will be `0`.
-        /// This parameter has no effect on non-negative operands.
+        /// If this is `{true}`, negative operands will not preserve their sign
+        /// bit, and bits which appear to the left after the shift will be
+        /// `{0}`. This parameter has no effect on non-negative operands.
         #[named]
         #[default(false)]
         logical: bool,