Improve internal documentation

crates/typst-library/src/layout/length.rs

@@ -76,6 +76,11 @@ impl Length {
         self.abs + self.em.at(font_size)
     }
 
+    /// Expresses this length in em's of the provided outer text size.
+    pub fn to_em(&self, text_size: Abs) -> Em {
+        self.em + Em::new(self.abs / text_size)
+    }
+
     /// Fails with an error if the length has a non-zero font-relative part.
     fn ensure_that_em_is_zero(&self, span: Span, unit: &str) -> SourceResult<()> {
         if self.em == Em::zero() {
@@ -91,10 +96,6 @@ impl Length {
             hint: "or use `length.abs.{unit}()` instead to ignore its em component"
         )
     }
-
-    pub fn to_em(&self, text_size: Abs) -> Em {
-        self.em + Em::new(self.abs / text_size)
-    }
 }
 
 #[scope]

crates/typst-library/src/text/font/mod.rs

@@ -313,13 +313,23 @@ pub struct LineMetrics {
 /// Metrics for subscripts or superscripts.
 #[derive(Debug, Copy, Clone)]
 pub struct ScriptMetrics {
+    /// The width of those scripts, relative to the outer font size.
     pub width: Em,
+    /// The height of those scripts, relative to the outer font size.
     pub height: Em,
+    /// The horizontal (to the right) offset of those scripts, relative to the
+    /// outer font size.
+    ///
+    /// This is used for italic correction.
     pub horizontal_offset: Em,
+    /// The vertical (to the top) offset of those scripts, relative to the outer font size.
+    ///
+    /// For superscripts, this is positive. For subscripts, this is negative.
     pub vertical_offset: Em,
 }
 
 impl ScriptMetrics {
+    /// Creates default script metrics with the specified vertical offset.
     pub const fn default_with_vertical_offset(offset: Em) -> Self {
         Self {
             width: Em::new(0.6),
@@ -329,10 +339,18 @@ impl ScriptMetrics {
         }
     }
 
+    /// Returns the default metrics for subscripts.
+    ///
+    /// This can be used as a last resort if neither the user nor the font
+    /// provided those metrics.
     pub const fn default_subscript() -> Self {
         Self::default_with_vertical_offset(Em::new(-0.2))
     }
 
+    /// Returns the default metrics for superscripts.
+    ///
+    /// This can be used as a last resort if neither the user nor the font
+    /// provided those metrics.
     pub const fn default_superscript() -> Self {
         Self::default_with_vertical_offset(Em::new(0.5))
     }

crates/typst-library/src/text/mod.rs

@@ -755,7 +755,7 @@ pub struct TextElem {
     #[ghost]
     pub smallcaps: Option<Smallcaps>,
 
-    /// Whether subscripts or superscripts are enabled.
+    /// The settings for superscripts or subscripts, if one of them is enabled.
     #[internal]
     #[ghost]
     pub subperscript: Option<ScriptSettings>,

crates/typst-library/src/text/shift.rs

@@ -134,6 +134,29 @@ impl Show for Packed<SuperElem> {
     }
 }
 
+/// Configuration values for sub- or superscript text.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
+pub struct ScriptSettings {
+    /// Whether the OpenType feature should be used if possible.
+    pub typographic: bool,
+    /// The baseline shift of the script, relative to the outer text size.
+    ///
+    /// For superscripts, this is positive. For subscripts, this is negative. A
+    /// value of [`Smart::Auto`] indicates that the value should be obtained
+    /// from font metrics.
+    pub shift: Smart<Em>,
+    /// The size of the script, relative to the outer text size.
+    ///
+    /// A value of [`Smart::Auto`] indicates that the value should be obtained
+    /// from font metrics.
+    pub size: Smart<Em>,
+    /// The kind of script (either a subscript, or a superscript).
+    ///
+    /// This is used to know which OpenType table to use to resolve
+    /// [`Smart::Auto`] values.
+    pub kind: ScriptKind,
+}
+
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
 pub enum ScriptKind {
     Sub,
@@ -141,6 +164,10 @@ pub enum ScriptKind {
 }
 
 impl ScriptKind {
+    /// Returns the default metrics for this script kind.
+    ///
+    /// This can be used as a last resort if neither the user nor the font
+    /// provided those metrics.
     pub const fn default_metrics(self) -> ScriptMetrics {
         match self {
             Self::Sub => ScriptMetrics::default_subscript(),
@@ -148,6 +175,7 @@ impl ScriptKind {
         }
     }
 
+    /// Reads the script metrics from the font table for to this script kind.
     pub const fn read_metrics(self, font_metrics: &FontMetrics) -> ScriptMetrics {
         match self {
             Self::Sub => font_metrics.subscript,
@@ -163,12 +191,3 @@ impl ScriptKind {
         }
     }
 }
-
-#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
-pub struct ScriptSettings {
-    /// Whether the OpenType feature should be used if possible.
-    pub typographic: bool,
-    pub shift: Smart<Em>,
-    pub size: Smart<Em>,
-    pub kind: ScriptKind,
-}