Documentation fixes and improvements (#5816)

14 files changed, 28 insertions, 43 deletions

diff --git a/crates/typst-layout/src/shapes.rs b/crates/typst-layout/src/shapes.rs
index eb665f06..21d0a518 100644
--- a/crates/typst-layout/src/shapes.rs
+++ b/crates/typst-layout/src/shapes.rs
@@ -1281,7 +1281,7 @@ impl ControlPoints {
     }
 }
 
-/// Helper to draw arcs with bezier curves.
+/// Helper to draw arcs with Bézier curves.
 trait CurveExt {
     fn arc(&mut self, start: Point, center: Point, end: Point);
     fn arc_move(&mut self, start: Point, center: Point, end: Point);
@@ -1305,7 +1305,7 @@ impl CurveExt for Curve {
     }
 }
 
-/// Get the control points for a bezier curve that approximates a circular arc for
+/// Get the control points for a Bézier curve that approximates a circular arc for
 /// a start point, an end point and a center of the circle whose arc connects
 /// the two.
 fn bezier_arc_control(start: Point, center: Point, end: Point) -> [Point; 2] {
diff --git a/crates/typst-library/src/foundations/plugin.rs b/crates/typst-library/src/foundations/plugin.rs
index a33f1cb9..31f8cd73 100644
--- a/crates/typst-library/src/foundations/plugin.rs
+++ b/crates/typst-library/src/foundations/plugin.rs
@@ -148,9 +148,7 @@ use crate::loading::{DataSource, Load};
 #[func(scope)]
 pub fn plugin(
     engine: &mut Engine,
-    /// A path to a WebAssembly file or raw WebAssembly bytes.
-    ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
+    /// A [path]($syntax/#paths) to a WebAssembly file or raw WebAssembly bytes.
     source: Spanned<DataSource>,
 ) -> SourceResult<Module> {
     let data = source.load(engine.world)?;
diff --git a/crates/typst-library/src/loading/cbor.rs b/crates/typst-library/src/loading/cbor.rs
index 801ca617..aa14c5c7 100644
--- a/crates/typst-library/src/loading/cbor.rs
+++ b/crates/typst-library/src/loading/cbor.rs
@@ -20,9 +20,7 @@ use crate::loading::{DataSource, Load};
 #[func(scope, title = "CBOR")]
 pub fn cbor(
     engine: &mut Engine,
-    /// A path to a CBOR file or raw CBOR bytes.
-    ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
+    /// A [path]($syntax/#paths) to a CBOR file or raw CBOR bytes.
     source: Spanned<DataSource>,
 ) -> SourceResult<Value> {
     let data = source.load(engine.world)?;
diff --git a/crates/typst-library/src/loading/csv.rs b/crates/typst-library/src/loading/csv.rs
index 6fdec445..6afb5bae 100644
--- a/crates/typst-library/src/loading/csv.rs
+++ b/crates/typst-library/src/loading/csv.rs
@@ -26,9 +26,7 @@ use crate::loading::{DataSource, Load, Readable};
 #[func(scope, title = "CSV")]
 pub fn csv(
     engine: &mut Engine,
-    /// Path to a CSV file or raw CSV bytes.
-    ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
+    /// A [path]($syntax/#paths) to a CSV file or raw CSV bytes.
     source: Spanned<DataSource>,
     /// The delimiter that separates columns in the CSV file.
     /// Must be a single ASCII character.
diff --git a/crates/typst-library/src/loading/json.rs b/crates/typst-library/src/loading/json.rs
index 185bac14..aa908cca 100644
--- a/crates/typst-library/src/loading/json.rs
+++ b/crates/typst-library/src/loading/json.rs
@@ -51,9 +51,7 @@ use crate::loading::{DataSource, Load, Readable};
 #[func(scope, title = "JSON")]
 pub fn json(
     engine: &mut Engine,
-    /// Path to a JSON file or raw JSON bytes.
-    ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
+    /// A [path]($syntax/#paths) to a JSON file or raw JSON bytes.
     source: Spanned<DataSource>,
 ) -> SourceResult<Value> {
     let data = source.load(engine.world)?;
diff --git a/crates/typst-library/src/loading/toml.rs b/crates/typst-library/src/loading/toml.rs
index 2660e7e7..f04b2e74 100644
--- a/crates/typst-library/src/loading/toml.rs
+++ b/crates/typst-library/src/loading/toml.rs
@@ -29,9 +29,7 @@ use crate::loading::{DataSource, Load, Readable};
 #[func(scope, title = "TOML")]
 pub fn toml(
     engine: &mut Engine,
-    /// A path to a TOML file or raw TOML bytes.
-    ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
+    /// A [path]($syntax/#paths) to a TOML file or raw TOML bytes.
     source: Spanned<DataSource>,
 ) -> SourceResult<Value> {
     let data = source.load(engine.world)?;
diff --git a/crates/typst-library/src/loading/xml.rs b/crates/typst-library/src/loading/xml.rs
index 32ed6f24..daccd02f 100644
--- a/crates/typst-library/src/loading/xml.rs
+++ b/crates/typst-library/src/loading/xml.rs
@@ -58,9 +58,7 @@ use crate::loading::{DataSource, Load, Readable};
 #[func(scope, title = "XML")]
 pub fn xml(
     engine: &mut Engine,
-    /// A path to an XML file or raw XML bytes.
-    ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
+    /// A [path]($syntax/#paths) to an XML file or raw XML bytes.
     source: Spanned<DataSource>,
 ) -> SourceResult<Value> {
     let data = source.load(engine.world)?;
diff --git a/crates/typst-library/src/loading/yaml.rs b/crates/typst-library/src/loading/yaml.rs
index 4eeec28f..3f48113e 100644
--- a/crates/typst-library/src/loading/yaml.rs
+++ b/crates/typst-library/src/loading/yaml.rs
@@ -41,9 +41,7 @@ use crate::loading::{DataSource, Load, Readable};
 #[func(scope, title = "YAML")]
 pub fn yaml(
     engine: &mut Engine,
-    /// A path to a YAML file or raw YAML bytes.
-    ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
+    /// A [path]($syntax/#paths) to a YAML file or raw YAML bytes.
     source: Spanned<DataSource>,
 ) -> SourceResult<Value> {
     let data = source.load(engine.world)?;
diff --git a/crates/typst-library/src/model/outline.rs b/crates/typst-library/src/model/outline.rs
index f413189b..7ceb530f 100644
--- a/crates/typst-library/src/model/outline.rs
+++ b/crates/typst-library/src/model/outline.rs
@@ -623,7 +623,7 @@ impl OutlineEntry {
 
     /// The content which is displayed in place of the referred element at its
     /// entry in the outline. For a heading, this is its
-    /// [`body`]($heading.body), for a figure a caption, and for equations it is
+    /// [`body`]($heading.body); for a figure a caption and for equations, it is
     /// empty.
     #[func]
     pub fn body(&self) -> StrResult<Content> {
diff --git a/crates/typst-library/src/pdf/embed.rs b/crates/typst-library/src/pdf/embed.rs
index f9ca3ca0..001078e5 100644
--- a/crates/typst-library/src/pdf/embed.rs
+++ b/crates/typst-library/src/pdf/embed.rs
@@ -32,12 +32,10 @@ use crate::World;
 ///   embedded file conforms to PDF/A-1 or PDF/A-2.
 #[elem(Show, Locatable)]
 pub struct EmbedElem {
-    /// Path of the file to be embedded.
+    /// The [path]($syntax/#paths) of the file to be embedded.
     ///
     /// Must always be specified, but is only read from if no data is provided
     /// in the following argument.
-    ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
     #[required]
     #[parse(
         let Spanned { v: path, span } =
diff --git a/crates/typst-library/src/visualize/curve.rs b/crates/typst-library/src/visualize/curve.rs
index 607d92ab..fb5151e8 100644
--- a/crates/typst-library/src/visualize/curve.rs
+++ b/crates/typst-library/src/visualize/curve.rs
@@ -10,12 +10,12 @@ use crate::foundations::{
 use crate::layout::{Abs, Axes, BlockElem, Length, Point, Rel, Size};
 use crate::visualize::{FillRule, Paint, Stroke};
 
-/// A curve consisting of movements, lines, and Beziér segments.
+/// A curve consisting of movements, lines, and Bézier segments.
 ///
 /// At any point in time, there is a conceptual pen or cursor.
 /// - Move elements move the cursor without drawing.
 /// - Line/Quadratic/Cubic elements draw a segment from the cursor to a new
-///   position, potentially with control point for a Beziér curve.
+///   position, potentially with control point for a Bézier curve.
 /// - Close elements draw a straight or smooth line back to the start of the
 ///   curve or the latest preceding move segment.
 ///
@@ -26,7 +26,7 @@ use crate::visualize::{FillRule, Paint, Stroke};
 /// or relative to the current pen/cursor position, that is, the position where
 /// the previous segment ended.
 ///
-/// Beziér curve control points can be skipped by passing `{none}` or
+/// Bézier curve control points can be skipped by passing `{none}` or
 /// automatically mirrored from the preceding segment by passing `{auto}`.
 ///
 /// # Example
@@ -88,7 +88,7 @@ pub struct CurveElem {
     #[fold]
     pub stroke: Smart<Option<Stroke>>,
 
-    /// The components of the curve, in the form of moves, line and Beziér
+    /// The components of the curve, in the form of moves, line and Bézier
     /// segment, and closes.
     #[variadic]
     pub components: Vec<CurveComponent>,
@@ -225,7 +225,7 @@ pub struct CurveLine {
     pub relative: bool,
 }
 
-/// Adds a quadratic Beziér curve segment from the last point to `end`, using
+/// Adds a quadratic Bézier curve segment from the last point to `end`, using
 /// `control` as the control point.
 ///
 /// ```example
@@ -245,9 +245,9 @@ pub struct CurveLine {
 /// ```
 #[elem(name = "quad", title = "Curve Quadratic Segment")]
 pub struct CurveQuad {
-    /// The control point of the quadratic Beziér curve.
+    /// The control point of the quadratic Bézier curve.
     ///
-    /// - If `{auto}` and this segment follows another quadratic Beziér curve,
+    /// - If `{auto}` and this segment follows another quadratic Bézier curve,
     ///   the previous control point will be mirrored.
     /// - If `{none}`, the control point defaults to `end`, and the curve will
     ///   be a straight line.
@@ -272,7 +272,7 @@ pub struct CurveQuad {
     pub relative: bool,
 }
 
-/// Adds a cubic Beziér curve segment from the last point to `end`, using
+/// Adds a cubic Bézier curve segment from the last point to `end`, using
 /// `control-start` and `control-end` as the control points.
 ///
 /// ```example
@@ -388,7 +388,7 @@ pub enum CloseMode {
     Straight,
 }
 
-/// A curve consisting of movements, lines, and Beziér segments.
+/// A curve consisting of movements, lines, and Bézier segments.
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub struct Curve(pub Vec<CurveItem>);
 
diff --git a/crates/typst-library/src/visualize/image/mod.rs b/crates/typst-library/src/visualize/image/mod.rs
index 18d40caa..97189e22 100644
--- a/crates/typst-library/src/visualize/image/mod.rs
+++ b/crates/typst-library/src/visualize/image/mod.rs
@@ -46,10 +46,11 @@ use crate::text::LocalName;
 /// ```
 #[elem(scope, Show, LocalName, Figurable)]
 pub struct ImageElem {
-    /// A path to an image file or raw bytes making up an image in one of the
-    /// supported [formats]($image.format).
+    /// A [path]($syntax/#paths) to an image file or raw bytes making up an
+    /// image in one of the supported [formats]($image.format).
     ///
-    /// For more details about paths, see the [Paths section]($syntax/#paths).
+    /// Bytes can be used to specify raw pixel data in a row-major,
+    /// left-to-right, top-to-bottom format.
     ///
     /// ```example
     /// #let original = read("diagram.svg")
diff --git a/crates/typst-library/src/visualize/path.rs b/crates/typst-library/src/visualize/path.rs
index c1cfde94..968146cd 100644
--- a/crates/typst-library/src/visualize/path.rs
+++ b/crates/typst-library/src/visualize/path.rs
@@ -8,7 +8,7 @@ use crate::foundations::{
 use crate::layout::{Axes, BlockElem, Length, Rel};
 use crate::visualize::{FillRule, Paint, Stroke};
 
-/// A path through a list of points, connected by Bezier curves.
+/// A path through a list of points, connected by Bézier curves.
 ///
 /// # Example
 /// ```example
@@ -59,8 +59,8 @@ pub struct PathElem {
     #[fold]
     pub stroke: Smart<Option<Stroke>>,
 
-    /// Whether to close this path with one last bezier curve. This curve will
-    /// takes into account the adjacent control points. If you want to close
+    /// Whether to close this path with one last Bézier curve. This curve will
+    /// take into account the adjacent control points. If you want to close
     /// with a straight line, simply add one last point that's the same as the
     /// start point.
     #[default(false)]
diff --git a/crates/typst-library/src/visualize/shape.rs b/crates/typst-library/src/visualize/shape.rs
index 3c62b210..439b4cd9 100644
--- a/crates/typst-library/src/visualize/shape.rs
+++ b/crates/typst-library/src/visualize/shape.rs
@@ -412,7 +412,7 @@ pub enum Geometry {
     Line(Point),
     /// A rectangle with its origin in the topleft corner.
     Rect(Size),
-    /// A curve consisting of movements, lines, and Bezier segments.
+    /// A curve consisting of movements, lines, and Bézier segments.
     Curve(Curve),
 }