From 6bd1a494e09dcc5c1793186f1868c0cae7445a6a Mon Sep 17 00:00:00 2001 From: Laurenz Date: Wed, 17 Mar 2021 23:29:58 +0100 Subject: [PATCH] =?UTF-8?q?Formatting=20and=20documentation=20=E2=9C=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/library/align.rs | 26 ++++++++++------- src/library/base.rs | 13 +++++---- src/library/font.rs | 66 ++++++++++++++++++++++-------------------- src/library/image.rs | 5 +++- src/library/pad.rs | 13 +++++---- src/library/page.rs | 40 ++++++++++++++++--------- src/library/shapes.rs | 23 ++++++++------- src/library/spacing.rs | 11 +++++-- 8 files changed, 118 insertions(+), 79 deletions(-) diff --git a/src/library/align.rs b/src/library/align.rs index 31367a5a1..a516ff4cc 100644 --- a/src/library/align.rs +++ b/src/library/align.rs @@ -2,26 +2,30 @@ use super::*; /// `align`: Align content along the layouting axes. /// +/// # Positional parameters +/// - Alignments: variadic, of type `alignment`. +/// - Body: optional, of type `template`. +/// /// Which axis an alignment should apply to (main or cross) is inferred from /// either the argument itself (for anything other than `center`) or from the /// second argument if present, defaulting to the cross axis for a single /// `center` alignment. /// -/// # Positional arguments -/// - Alignments: variadic, of type `alignment`. -/// - Body: optional, of type `template`. -/// -/// # Named arguments +/// # Named parameters /// - Horizontal alignment: `horizontal`, of type `alignment`. -/// - Vertical alignment: `vertical`, of type `alignment`. +/// - Vertical alignment: `vertical`, of type `alignment`. +/// +/// # Return value +/// A template that changes the alignment along the layouting axes. The effect +/// is scoped to the body if present. /// /// # Relevant types and constants /// - Type `alignment` -/// - `left` -/// - `right` -/// - `top` -/// - `bottom` -/// - `center` +/// - `left` +/// - `right` +/// - `top` +/// - `bottom` +/// - `center` pub fn align(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { let first = args.find(ctx); let second = args.find(ctx); diff --git a/src/library/base.rs b/src/library/base.rs index 3d067faa8..4d36b878f 100644 --- a/src/library/base.rs +++ b/src/library/base.rs @@ -5,7 +5,7 @@ use super::*; /// `repr`: Get the string representation of a value. /// -/// # Positional arguments +/// # Positional parameters /// - Any value. /// /// # Return value @@ -19,11 +19,14 @@ pub fn repr(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { /// `rgb`: Create an RGB(A) color. /// -/// # Positional arguments -/// - Red component: of type `float`, between 0.0 and 1.0. +/// # Positional parameters +/// - Red component: of type `float`, between 0.0 and 1.0. /// - Green component: of type `float`, between 0.0 and 1.0. -/// - Blue component: of type `float`, between 0.0 and 1.0. +/// - Blue component: of type `float`, between 0.0 and 1.0. /// - Alpha component: optional, of type `float`, between 0.0 and 1.0. +/// +/// # Return value +/// The color with the given components. pub fn rgb(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { let r = args.require(ctx, "red component"); let g = args.require(ctx, "green component"); @@ -49,7 +52,7 @@ pub fn rgb(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { /// `type`: Find out the name of a value's type. /// -/// # Positional arguments +/// # Positional parameters /// - Any value. /// /// # Return value diff --git a/src/library/font.rs b/src/library/font.rs index 79cc85188..460cfba16 100644 --- a/src/library/font.rs +++ b/src/library/font.rs @@ -4,44 +4,48 @@ use super::*; /// `font`: Configure the font. /// -/// # Positional arguments -/// - Font size: optional, of type `linear` relative to current font size. +/// # Positional parameters +/// - Font size: optional, of type `linear` relative to current font size. /// - Font families: variadic, of type `font-family`. -/// - Body: optional, of type `template`. +/// - Body: optional, of type `template`. /// -/// # Named arguments -/// - Font Style: `style`, of type `font-style`. -/// - Font Weight: `weight`, of type `font-weight`. -/// - Serif family definition: `serif`, of type `font-families`. -/// - Sans-serif family definition: `sans-serif`, of type `font-families`. -/// - Monospace family definition: `monospace`, of type `font-families`. -/// - Font Stretch: `stretch`, of type `relative`, between 0.5 and 2.0. +/// # Named parameters +/// - Font Style: `style`, of type `font-style`. +/// - Font Weight: `weight`, of type `font-weight`. +/// - Font Stretch: `stretch`, of type `relative`, between 0.5 and 2.0. +/// - Serif family definition: `serif`, of type `font-familiy-list`. +/// - Sans-serif family definition: `sans-serif`, of type `font-familiy-list`. +/// - Monospace family definition: `monospace`, of type `font-familiy-list`. +/// +/// # Return value +/// A template that configures font properties. The effect is scoped to the body +/// if present. /// /// # Relevant types and constants -/// - Type `font-families` -/// - coerces from `string` -/// - coerces from `array` -/// - coerces from `font-family` +/// - Type `font-family-list` +/// - coerces from `string` +/// - coerces from `array` +/// - coerces from `font-family` /// - Type `font-family` -/// - `serif` -/// - `sans-serif` -/// - `monospace` -/// - coerces from `string` +/// - `serif` +/// - `sans-serif` +/// - `monospace` +/// - coerces from `string` /// - Type `font-style` -/// - `normal` -/// - `italic` -/// - `oblique` +/// - `normal` +/// - `italic` +/// - `oblique` /// - Type `font-weight` -/// - `thin` (100) -/// - `extralight` (200) -/// - `light` (300) -/// - `regular` (400) -/// - `medium` (500) -/// - `semibold` (600) -/// - `bold` (700) -/// - `extrabold` (800) -/// - `black` (900) -/// - coerces from `integer` +/// - `thin` (100) +/// - `extralight` (200) +/// - `light` (300) +/// - `regular` (400) +/// - `medium` (500) +/// - `semibold` (600) +/// - `bold` (700) +/// - `extrabold` (800) +/// - `black` (900) +/// - coerces from `integer` pub fn font(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { let size = args.find::(ctx); let list: Vec<_> = args.filter::(ctx).map(|f| f.to_string()).collect(); diff --git a/src/library/image.rs b/src/library/image.rs index d9c0a0a7d..c3200e939 100644 --- a/src/library/image.rs +++ b/src/library/image.rs @@ -8,8 +8,11 @@ use crate::layout::*; /// /// Supports PNG and JPEG files. /// -/// # Positional arguments +/// # Positional parameters /// - Path to image file: of type `string`. +/// +/// # Return value +/// A template that inserts an image. pub fn image(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { let path = args.require::>(ctx, "path to image file"); let width = args.get(ctx, "width"); diff --git a/src/library/pad.rs b/src/library/pad.rs index ba28bf8e1..5d59f2b36 100644 --- a/src/library/pad.rs +++ b/src/library/pad.rs @@ -2,15 +2,18 @@ use super::*; /// `pad`: Pad content at the sides. /// -/// # Positional arguments +/// # Positional parameters /// - Padding for all sides: `padding`, of type `linear` relative to sides. /// - Body: of type `template`. /// -/// # Named arguments -/// - Left padding: `left`, of type `linear` relative to parent width. -/// - Right padding: `right`, of type `linear` relative to parent width. -/// - Top padding: `top`, of type `linear` relative to parent height. +/// # Named parameters +/// - Left padding: `left`, of type `linear` relative to parent width. +/// - Right padding: `right`, of type `linear` relative to parent width. +/// - Top padding: `top`, of type `linear` relative to parent height. /// - Bottom padding: `bottom`, of type `linear` relative to parent height. +/// +/// # Return value +/// A template that pads the body at the sides. pub fn pad(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { let all = args.find(ctx); let left = args.get(ctx, "left"); diff --git a/src/library/page.rs b/src/library/page.rs index 20d7f0696..17021607d 100644 --- a/src/library/page.rs +++ b/src/library/page.rs @@ -3,22 +3,33 @@ use crate::paper::{Paper, PaperClass}; /// `page`: Configure pages. /// -/// # Positional arguments +/// # Positional parameters /// - Paper name: optional, of type `string`, see [here](crate::paper) for a -/// full list of all paper names. -/// - Body: optional, of type `template`. +/// full list of all paper names. +/// - Body: optional, of type `template`. /// -/// # Named arguments -/// - Width of the page: `width`, of type `length`. -/// - Height of the page: `height`, of type `length`. -/// - Margins for all sides: `margins`, of type `linear` relative to sides. -/// - Left margin: `left`, of type `linear` relative to width. -/// - Right margin: `right`, of type `linear` relative to width. -/// - Top margin: `top`, of type `linear` relative to height. -/// - Bottom margin: `bottom`, of type `linear` relative to height. -/// - Flip width and height: `flip`, of type `bool`. -/// - Main layouting direction: `main-dir`, of type `direction`. +/// # Named parameters +/// - Width of the page: `width`, of type `length`. +/// - Height of the page: `height`, of type `length`. +/// - Margins for all sides: `margins`, of type `linear` relative to sides. +/// - Left margin: `left`, of type `linear` relative to width. +/// - Right margin: `right`, of type `linear` relative to width. +/// - Top margin: `top`, of type `linear` relative to height. +/// - Bottom margin: `bottom`, of type `linear` relative to height. +/// - Flip width and height: `flip`, of type `bool`. +/// - Main layouting direction: `main-dir`, of type `direction`. /// - Cross layouting direction: `cross-dir`, of type `direction`. +/// +/// # Return value +/// A template that configures page properties. The effect is scoped to the body +/// if present. +/// +/// # Relevant types and constants +/// - Type `direction` +/// - `ltr` (left to right) +/// - `rtl` (right to left) +/// - `ttb` (top to bottom) +/// - `btt` (bottom to top) pub fn page(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { let paper = args.find::>(ctx).and_then(|name| { Paper::from_name(&name.v).or_else(|| { @@ -96,6 +107,9 @@ pub fn page(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { } /// `pagebreak`: Start a new page. +/// +/// # Return value +/// A template that starts a new page. pub fn pagebreak(_: &mut EvalContext, args: &mut ValueArgs) -> Value { let span = args.span; Value::template("pagebreak", move |ctx| { diff --git a/src/library/shapes.rs b/src/library/shapes.rs index 41be3b2b2..48bc7ebd1 100644 --- a/src/library/shapes.rs +++ b/src/library/shapes.rs @@ -2,22 +2,25 @@ use super::*; /// `rect`: Create a rectangular box. /// -/// # Positional arguments +/// # Positional parameters /// - Body: optional, of type `template`. /// -/// # Named arguments -/// - Width of the box: `width`, of type `linear` relative to parent width. -/// - Height of the box: `height`, of type `linear` relative to parent height. -/// - Main layouting direction: `main-dir`, of type `direction`. +/// # Named parameters +/// - Width of the box: `width`, of type `linear` relative to parent width. +/// - Height of the box: `height`, of type `linear` relative to parent height. +/// - Main layouting direction: `main-dir`, of type `direction`. /// - Cross layouting direction: `cross-dir`, of type `direction`. -/// - Fill color of the box: `fill`, of type `color`. +/// - Fill color of the box: `fill`, of type `color`. +/// +/// # Return value +/// A template that places the body into a rectangle. /// /// # Relevant types and constants /// - Type `direction` -/// - `ltr` (left to right) -/// - `rtl` (right to left) -/// - `ttb` (top to bottom) -/// - `btt` (bottom to top) +/// - `ltr` (left to right) +/// - `rtl` (right to left) +/// - `ttb` (top to bottom) +/// - `btt` (bottom to top) pub fn rect(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { let width = args.get(ctx, "width"); let height = args.get(ctx, "height"); diff --git a/src/library/spacing.rs b/src/library/spacing.rs index 3cc718b2f..d8f18f419 100644 --- a/src/library/spacing.rs +++ b/src/library/spacing.rs @@ -2,16 +2,22 @@ use super::*; /// `h`: Add horizontal spacing. /// -/// # Positional arguments +/// # Positional parameters /// - Amount of spacing: of type `linear` relative to current font size. +/// +/// # Return value +/// A template that adds horizontal spacing. pub fn h(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { spacing(ctx, args, SpecAxis::Horizontal) } /// `v`: Add vertical spacing. /// -/// # Positional arguments +/// # Positional parameters /// - Amount of spacing: of type `linear` relative to current font size. +/// +/// # Return value +/// A template that adds vertical spacing. pub fn v(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { spacing(ctx, args, SpecAxis::Vertical) } @@ -19,7 +25,6 @@ pub fn v(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value { /// Apply spacing along a specific axis. fn spacing(ctx: &mut EvalContext, args: &mut ValueArgs, axis: SpecAxis) -> Value { let spacing: Option = args.require(ctx, "spacing"); - Value::template("spacing", move |ctx| { if let Some(linear) = spacing { let amount = linear.resolve(ctx.state.font.font_size());