Many fixes

7 files changed, 50 insertions, 68 deletions

diff --git a/src/library/text/deco.rs b/src/library/text/deco.rs
index c5217e8e..e6a65eba 100644
--- a/src/library/text/deco.rs
+++ b/src/library/text/deco.rs
@@ -20,8 +20,8 @@ pub type OverlineNode = DecoNode<OVERLINE>;
 
 #[node(showable)]
 impl<const L: DecoLine> DecoNode<L> {
-    /// How to stroke the line. The text color and thickness read from the font
-    /// tables if `auto`.
+    /// How to stroke the line. The text color and thickness are read from the
+    /// font tables if `auto`.
     #[property(shorthand, resolve, fold)]
     pub const STROKE: Smart<RawStroke> = Smart::Auto;
     /// Position of the line relative to the baseline, read from the font tables
diff --git a/src/library/text/link.rs b/src/library/text/link.rs
index 12cbaf59..740426a3 100644
--- a/src/library/text/link.rs
+++ b/src/library/text/link.rs
@@ -1,7 +1,7 @@
 use super::TextNode;
 use crate::library::prelude::*;
 
-/// Link text and other elements to an URL.
+/// Link text and other elements to a destination.
 #[derive(Debug, Hash)]
 pub struct LinkNode {
     /// The destination the link points to.
@@ -15,7 +15,7 @@ impl LinkNode {
     /// The fill color of text in the link. Just the surrounding text color
     /// if `auto`.
     pub const FILL: Smart<Paint> = Smart::Auto;
-    /// Whether to underline link.
+    /// Whether to underline the link.
     pub const UNDERLINE: Smart<bool> = Smart::Auto;
 
     fn construct(_: &mut Machine, args: &mut Args) -> TypResult<Content> {
@@ -35,10 +35,10 @@ castable! {
     Expected: "string or dictionary with `page`, `x`, and `y` keys",
     Value::Str(string) => Self::Url(string),
     Value::Dict(dict) => {
-        let page: i64 = dict.get(&"page".into())?.clone().cast()?;
-        let x: RawLength = dict.get(&"x".into())?.clone().cast()?;
-        let y: RawLength = dict.get(&"y".into())?.clone().cast()?;
-        Self::Internal(Location { page: page as usize, pos: Point::new(x.length, y.length) })
+        let page = dict.get("page")?.clone().cast()?;
+        let x: RawLength = dict.get("x")?.clone().cast()?;
+        let y: RawLength = dict.get("y")?.clone().cast()?;
+        Self::Internal(Location { page, pos: Point::new(x.length, y.length) })
     },
 }
 
diff --git a/src/library/text/mod.rs b/src/library/text/mod.rs
index be20b3ef..91eab2fd 100644
--- a/src/library/text/mod.rs
+++ b/src/library/text/mod.rs
@@ -59,13 +59,13 @@ impl TextNode {
     /// The amount of space that should be added between characters.
     #[property(resolve)]
     pub const TRACKING: RawLength = RawLength::zero();
-    /// The width of spaces relative to the default space width.
+    /// The width of spaces relative to the font's space width.
     #[property(resolve)]
     pub const SPACING: Relative<RawLength> = Relative::one();
     /// The offset of the baseline.
     #[property(resolve)]
     pub const BASELINE: RawLength = RawLength::zero();
-    /// Whether glyphs can hang over into the margin.
+    /// Whether certain glyphs can hang over into the margin.
     pub const OVERHANG: bool = true;
     /// The top end of the text bounding box.
     pub const TOP_EDGE: TextEdge = TextEdge::Metric(VerticalFontMetric::CapHeight);
@@ -114,7 +114,7 @@ impl TextNode {
     /// Whether the font weight should be increased by 300.
     #[property(skip, fold)]
     pub const BOLD: Toggle = false;
-    /// Whether the the font style should be inverted.
+    /// Whether the font style should be inverted.
     #[property(skip, fold)]
     pub const ITALIC: Toggle = false;
     /// A case transformation that should be applied to the text.
@@ -123,7 +123,7 @@ impl TextNode {
     /// Whether small capital glyphs should be used. ("smcp")
     #[property(skip)]
     pub const SMALLCAPS: bool = false;
-    /// An URL the text should link to.
+    /// A destination the text should be linked to.
     #[property(skip, referenced)]
     pub const LINK: Option<Destination> = None;
     /// Decorative lines.
@@ -168,7 +168,7 @@ impl TextNode {
     }
 }
 
-/// A font family like "Arial".
+/// A lowercased font family like "arial".
 #[derive(Clone, Eq, PartialEq, Hash)]
 pub struct FontFamily(EcoString);
 
@@ -338,7 +338,7 @@ impl Resolve for Smart<Hyphenate> {
 pub struct StylisticSet(u8);
 
 impl StylisticSet {
-    /// Creates a new set, clamping to 1-20.
+    /// Create a new set, clamping to 1-20.
     pub fn new(index: u8) -> Self {
         Self(index.clamp(1, 20))
     }
@@ -363,7 +363,7 @@ castable! {
 pub enum NumberType {
     /// Numbers that fit well with capital text. ("lnum")
     Lining,
-    /// Numbers that fit well into flow of upper- and lowercase text. ("onum")
+    /// Numbers that fit well into a flow of upper- and lowercase text. ("onum")
     OldStyle,
 }
 
@@ -396,28 +396,6 @@ castable! {
     },
 }
 
-/// How to position numbers.
-#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
-pub enum NumberPosition {
-    /// Numbers are positioned on the same baseline as text.
-    Normal,
-    /// Numbers are smaller and placed at the bottom. ("subs")
-    Subscript,
-    /// Numbers are smaller and placed at the top. ("sups")
-    Superscript,
-}
-
-castable! {
-    NumberPosition,
-    Expected: "string",
-    Value::Str(string) => match string.as_str() {
-        "normal" => Self::Normal,
-        "subscript" => Self::Subscript,
-        "superscript" => Self::Superscript,
-        _ => Err(r#"expected "normal", "subscript" or "superscript""#)?,
-    },
-}
-
 castable! {
     Vec<(Tag, u32)>,
     Expected: "array of strings or dictionary mapping tags to integers",
@@ -445,12 +423,12 @@ impl Fold for Vec<(Tag, u32)> {
     }
 }
 
-/// Convert text to lowercase.
+/// Convert a string or content to lowercase.
 pub fn lower(_: &mut Machine, args: &mut Args) -> TypResult<Value> {
     case(Case::Lower, args)
 }
 
-/// Convert text to uppercase.
+/// Convert a string or content to uppercase.
 pub fn upper(_: &mut Machine, args: &mut Args) -> TypResult<Value> {
     case(Case::Upper, args)
 }
@@ -475,7 +453,7 @@ pub enum Case {
 }
 
 impl Case {
-    /// Apply the case to a string of text.
+    /// Apply the case to a string.
     pub fn apply(self, text: &str) -> String {
         match self {
             Self::Upper => text.to_uppercase(),
diff --git a/src/library/text/par.rs b/src/library/text/par.rs
index e4013163..38240b3d 100644
--- a/src/library/text/par.rs
+++ b/src/library/text/par.rs
@@ -297,7 +297,7 @@ impl Segment<'_> {
 /// A prepared item in a paragraph layout.
 #[derive(Debug)]
 enum Item<'a> {
-    /// A shaped text run with consistent direction.
+    /// A shaped text run with consistent style and direction.
     Text(ShapedText<'a>),
     /// Absolute spacing between other items.
     Absolute(Length),
@@ -305,7 +305,7 @@ enum Item<'a> {
     Fractional(Fraction),
     /// A layouted child node.
     Frame(Frame),
-    /// A repeating node.
+    /// A repeating node that fills the remaining space.
     Repeat(&'a RepeatNode, StyleChain<'a>),
     /// A pin identified by index.
     Pin(usize),
@@ -330,7 +330,7 @@ impl<'a> Item<'a> {
         }
     }
 
-    /// The natural width of the item.
+    /// The natural layouted width of the item.
     fn width(&self) -> Length {
         match self {
             Self::Text(shaped) => shaped.width,
@@ -366,7 +366,7 @@ struct Line<'a> {
     last: Option<Item<'a>>,
     /// The width of the line.
     width: Length,
-    /// Whether the line is allowed to be justified.
+    /// Whether the line should be justified.
     justify: bool,
     /// Whether the line ends with a hyphen or dash, either naturally or through
     /// hyphenation.
@@ -403,7 +403,7 @@ impl<'a> Line<'a> {
         self.items().skip(start).take(end - start)
     }
 
-    // How many justifiable glyphs the line contains.
+    /// How many justifiable glyphs the line contains.
     fn justifiables(&self) -> usize {
         let mut count = 0;
         for shaped in self.items().filter_map(Item::text) {
@@ -528,7 +528,7 @@ fn prepare<'a>(
     let mut cursor = 0;
     let mut items = vec![];
 
-    // Layout the children and collect them into items.
+    // Shape / layout the children and collect them into items.
     for (segment, styles) in segments {
         let end = cursor + segment.len();
         match segment {
@@ -654,7 +654,7 @@ fn linebreak<'a>(
 }
 
 /// Perform line breaking in simple first-fit style. This means that we build
-/// lines a greedily, always taking the longest possible line. This may lead to
+/// lines greedily, always taking the longest possible line. This may lead to
 /// very unbalanced line, but is fast and simple.
 fn linebreak_simple<'a>(
     p: &'a Preparation<'a>,
@@ -670,8 +670,8 @@ fn linebreak_simple<'a>(
         let mut attempt = line(p, fonts, start .. end, mandatory, hyphen);
 
         // If the line doesn't fit anymore, we push the last fitting attempt
-        // into the stack and rebuild the line from its end. The resulting
-        // line cannot be broken up further.
+        // into the stack and rebuild the line from the attempt's end. The
+        // resulting line cannot be broken up further.
         if !width.fits(attempt.width) {
             if let Some((last_attempt, last_end)) = last.take() {
                 lines.push(last_attempt);
@@ -771,17 +771,18 @@ fn linebreak_optimized<'a>(
             ratio = ratio.min(10.0);
 
             // Determine the cost of the line.
-            let mut cost = if ratio < if attempt.justify { MIN_RATIO } else { 0.0 } {
+            let min_ratio = if attempt.justify { MIN_RATIO } else { 0.0 };
+            let mut cost = if ratio < min_ratio {
                 // The line is overfull. This is the case if
-                // - justification is on, but we'd need to shrink to much
+                // - justification is on, but we'd need to shrink too much
                 // - justification is off and the line just doesn't fit
                 // Since any longer line will also be overfull, we can deactive
                 // this breakpoint.
                 active = i + 1;
                 MAX_COST
             } else if eof {
-                // This is the final line and its not overfull since then
-                // we would have taken the above branch.
+                // This is the final line and its not overfull since then we
+                // would have taken the above branch.
                 0.0
             } else if mandatory {
                 // This is a mandatory break and the line is not overfull, so it
diff --git a/src/library/text/repeat.rs b/src/library/text/repeat.rs
index a3e83ac7..aca281fc 100644
--- a/src/library/text/repeat.rs
+++ b/src/library/text/repeat.rs
@@ -1,6 +1,6 @@
 use crate::library::prelude::*;
 
-/// Fill space by repeating something horizontally.
+/// A node that should be repeated to fill up a line.
 #[derive(Debug, Hash)]
 pub struct RepeatNode(pub LayoutNode);
 
diff --git a/src/library/text/shaping.rs b/src/library/text/shaping.rs
index bb88836c..9465fbd9 100644
--- a/src/library/text/shaping.rs
+++ b/src/library/text/shaping.rs
@@ -43,7 +43,9 @@ pub struct ShapedGlyph {
     pub x_offset: Em,
     /// The vertical offset of the glyph.
     pub y_offset: Em,
-    /// A value that is the same for all glyphs belong to one cluster.
+    /// The byte index in the source text where this glyph's cluster starts. A
+    /// cluster is a sequence of one or multiple glyphs that cannot be
+    /// separated and must always be treated as a union.
     pub cluster: usize,
     /// Whether splitting the shaping result before this glyph would yield the
     /// same results as shaping the parts to both sides of `text_index`
@@ -67,9 +69,9 @@ impl ShapedGlyph {
 
 /// A side you can go toward.
 enum Side {
-    /// Go toward the west.
+    /// To the left-hand side.
     Left,
-    /// Go toward the east.
+    /// To the right-hand side.
     Right,
 }
 
@@ -141,7 +143,7 @@ impl<'a> ShapedText<'a> {
         frame
     }
 
-    /// Measure the top and bottom extent of a this text.
+    /// Measure the top and bottom extent of this text.
     fn measure(&self, fonts: &mut FontStore) -> (Length, Length) {
         let mut top = Length::zero();
         let mut bottom = Length::zero();
@@ -498,7 +500,7 @@ fn shape_tofus(ctx: &mut ShapingContext, base: usize, text: &str, face_id: FaceI
     }
 }
 
-/// Apply tracking and spacing to a slice of shaped glyphs.
+/// Apply tracking and spacing to the shaped glyphs.
 fn track_and_space(ctx: &mut ShapingContext) {
     let tracking = Em::from_length(ctx.styles.get(TextNode::TRACKING), ctx.size);
     let spacing = ctx
@@ -522,7 +524,7 @@ fn track_and_space(ctx: &mut ShapingContext) {
     }
 }
 
-/// Resolve the font variant with `STRONG` and `EMPH` factored in.
+/// Resolve the font variant with `BOLD` and `ITALIC` factored in.
 pub fn variant(styles: StyleChain) -> FontVariant {
     let mut variant = FontVariant::new(
         styles.get(TextNode::STYLE),
diff --git a/src/library/text/shift.rs b/src/library/text/shift.rs
index 4eacd3c8..744479f2 100644
--- a/src/library/text/shift.rs
+++ b/src/library/text/shift.rs
@@ -3,11 +3,12 @@ use crate::font::FontStore;
 use crate::library::prelude::*;
 use crate::util::EcoString;
 
-/// Sub or superscript text. The text is rendered smaller and its baseline is raised.
+/// Sub or superscript text.
 ///
-/// To provide the best typography possible, we first try to transform the
-/// text to superscript codepoints. If that fails, we fall back to rendering
-/// shrunk normal letters in a raised way.
+/// The text is rendered smaller and its baseline is raised. To provide the best
+/// typography possible, we first try to transform the text to superscript
+/// codepoints. If that fails, we fall back to rendering shrunk normal letters
+/// in a raised way.
 #[derive(Debug, Hash)]
 pub struct ShiftNode<const S: ScriptKind>(pub Content);
 
@@ -19,7 +20,8 @@ pub type SubNode = ShiftNode<SUBSCRIPT>;
 
 #[node]
 impl<const S: ScriptKind> ShiftNode<S> {
-    /// Whether to prefer the dedicated sub- and superscript characters of the font.
+    /// Whether to prefer the dedicated sub- and superscript characters of the
+    /// font.
     pub const TYPOGRAPHIC: bool = true;
     /// The baseline shift for synthetic sub- and superscripts.
     pub const BASELINE: RawLength =
@@ -60,9 +62,8 @@ impl<const S: ScriptKind> Show for ShiftNode<S> {
     }
 }
 
-/// Find and transform the text contained in `content` iff it only consists of
-/// `Text`, `Space`, and `Empty` leaf nodes. The text is transformed to the
-/// given script kind.
+/// Find and transform the text contained in `content` to the given script kind
+/// if and only if it only consists of `Text`, `Space`, and `Empty` leaf nodes.
 fn search_text(content: &Content, mode: ScriptKind) -> Option<EcoString> {
     match content {
         Content::Text(_) => {