More consistent documentation 📝

src/library/base.rs

@@ -3,7 +3,7 @@ use crate::pretty::pretty;
 
 use super::*;
 
-/// `type`: Get the name of a value's type.
+/// `type`: The name of a value's type.
 ///
 /// # Positional parameters
 /// - Any value.
@@ -17,7 +17,7 @@ pub fn type_(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     }
 }
 
-/// `repr`: Get the string representation of a value.
+/// `repr`: The string representation of a value.
 ///
 /// # Positional parameters
 /// - Any value.
@@ -31,7 +31,7 @@ pub fn repr(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     }
 }
 
-/// `rgb`: Construct an RGB(A) color.
+/// `rgb`: Create an RGB(A) color.
 ///
 /// # Positional parameters
 /// - Red component: of type `float`, between 0.0 and 1.0.

src/library/image.rs

@@ -6,7 +6,7 @@ use crate::layout::{
     AnyNode, Areas, Element, Fragment, Frame, Image, Layout, LayoutContext,
 };
 
-/// `image`: Insert an image.
+/// `image`: An image.
 ///
 /// Supports PNG and JPEG files.
 ///

src/library/markup.rs

@@ -28,7 +28,7 @@ pub fn parbreak(_: &mut EvalContext, _: &mut FuncArgs) -> Value {
     })
 }
 
-/// `strong`: Signify important text by setting it in bold.
+/// `strong`: Strong text.
 ///
 /// # Syntax
 /// This function has dedicated syntax.
@@ -40,7 +40,7 @@ pub fn parbreak(_: &mut EvalContext, _: &mut FuncArgs) -> Value {
 /// - Body: optional, of type `template`.
 ///
 /// # Return value
-/// A template that flips the strongness of text. The effect is scoped to the
+/// A template that flips the boldness of text. The effect is scoped to the
 /// body if present.
 pub fn strong(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     let body = args.find::<TemplateValue>(ctx);
@@ -55,7 +55,7 @@ pub fn strong(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     })
 }
 
-/// `emph`: Emphasize text by setting it in italics.
+/// `emph`: Emphasized text.
 ///
 /// # Syntax
 /// This function has dedicated syntax.
@@ -67,8 +67,8 @@ pub fn strong(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
 /// - Body: optional, of type `template`.
 ///
 /// # Return value
-/// A template that flips whether text is emphasized. The effect is scoped to
-/// the body if present.
+/// A template that flips whether text is set in italics. The effect is scoped
+/// to the body if present.
 pub fn emph(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     let body = args.find::<TemplateValue>(ctx);
     Value::template(Node::EMPH, move |ctx| {
@@ -146,7 +146,7 @@ pub fn heading(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
 ///   type `boolean`.
 ///
 /// # Return value
-/// A template that sets the text raw, that is, in monospace with optional
+/// A template that sets the text raw, that is, in monospace and optionally with
 /// syntax highlighting.
 pub fn raw(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     let text = args.require::<String>(ctx, RawNode::TEXT).unwrap_or_default();

src/library/mod.rs

@@ -53,12 +53,12 @@ pub fn _new() -> Scope {
     }
 
     // Syntax functions.
-    func!(Node::EMPH, emph);
-    func!(Node::HEADING, heading);
-    func!(Node::STRONG, strong);
-    func!(Node::RAW, raw);
     func!(Node::LINEBREAK, linebreak);
     func!(Node::PARBREAK, parbreak);
+    func!(Node::STRONG, strong);
+    func!(Node::EMPH, emph);
+    func!(Node::HEADING, heading);
+    func!(Node::RAW, raw);
 
     // Library functions.
     func!("align", align);

src/library/pad.rs

@@ -14,7 +14,7 @@ use crate::layout::PadNode;
 /// - Bottom padding: `bottom`, of type `linear` relative to parent height.
 ///
 /// # Return value
-/// A template that pads the body at the sides.
+/// A template that sets the body into a padded area.
 pub fn pad(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     let all = args.find(ctx);
     let left = args.get(ctx, "left");

src/library/shapes.rs

@@ -4,7 +4,7 @@ use super::*;
 use crate::color::Color;
 use crate::layout::{BackgroundNode, BackgroundShape, Fill, FixedNode, PadNode};
 
-/// `rect`: Create a rectangle.
+/// `rect`: A rectangle with optional content.
 ///
 /// # Positional parameters
 /// - Body: optional, of type `template`.
@@ -15,7 +15,7 @@ use crate::layout::{BackgroundNode, BackgroundShape, Fill, FixedNode, PadNode};
 /// - Fill color: `fill`, of type `color`.
 ///
 /// # Return value
-/// A template that places the body into a rectangle.
+/// A template that inserts a rectangle and sets the body into it.
 pub fn rect(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     let width = args.get(ctx, "width");
     let height = args.get(ctx, "height");
@@ -24,7 +24,7 @@ pub fn rect(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     rect_impl("rect", width, height, None, fill, body)
 }
 
-/// `square`: Create a square.
+/// `square`: A square with optional content.
 ///
 /// # Positional parameters
 /// - Body: optional, of type `template`.
@@ -40,7 +40,7 @@ pub fn rect(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
 /// to its parent's size, which isn't possible by setting the side length.
 ///
 /// # Return value
-/// A template that places the body into a square.
+/// A template that inserts a square and sets the body into it.
 pub fn square(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     let length = args.get::<Length>(ctx, "length").map(Linear::from);
     let width = length.or_else(|| args.get(ctx, "width"));
@@ -77,7 +77,7 @@ fn rect_impl(
     })
 }
 
-/// `ellipse`: Create an ellipse.
+/// `ellipse`: An ellipse with optional content.
 ///
 /// # Positional parameters
 /// - Body: optional, of type `template`.
@@ -88,7 +88,7 @@ fn rect_impl(
 /// - Fill color: `fill`, of type `color`.
 ///
 /// # Return value
-/// A template that places the body into an ellipse.
+/// A template that inserts an ellipse and sets the body into it.
 pub fn ellipse(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     let width = args.get(ctx, "width");
     let height = args.get(ctx, "height");
@@ -97,7 +97,7 @@ pub fn ellipse(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     ellipse_impl("ellipse", width, height, None, fill, body)
 }
 
-/// `circle`: Create a circle.
+/// `circle`: A circle with optional content.
 ///
 /// # Positional parameters
 /// - Body: optional, of type `template`.
@@ -113,7 +113,7 @@ pub fn ellipse(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
 /// to its parent's size, which isn't possible by setting the radius.
 ///
 /// # Return value
-/// A template that places the body into a circle.
+/// A template that inserts a circle and sets the body into it.
 pub fn circle(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     let radius = args.get::<Length>(ctx, "radius").map(|r| 2.0 * Linear::from(r));
     let width = radius.or_else(|| args.get(ctx, "width"));

src/library/spacing.rs

@@ -1,24 +1,24 @@
 use super::*;
 use crate::layout::SpacingNode;
 
-/// `h`: Insert horizontal spacing.
+/// `h`: Horizontal spacing.
 ///
 /// # Positional parameters
 /// - Amount of spacing: of type `linear` relative to current font size.
 ///
 /// # Return value
-/// A template that adds horizontal spacing.
+/// A template that inserts horizontal spacing.
 pub fn h(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     spacing_impl(ctx, args, SpecAxis::Horizontal)
 }
 
-/// `v`: Insert vertical spacing.
+/// `v`: Vertical spacing.
 ///
 /// # Positional parameters
 /// - Amount of spacing: of type `linear` relative to current font size.
 ///
 /// # Return value
-/// A template that adds vertical spacing.
+/// A template that inserts vertical spacing.
 pub fn v(ctx: &mut EvalContext, args: &mut FuncArgs) -> Value {
     spacing_impl(ctx, args, SpecAxis::Vertical)
 }