Document parameters in comment

13 files changed, 193 insertions, 35 deletions

diff --git a/library/src/layout/align.rs b/library/src/layout/align.rs
index f00aeaf2..7853d84d 100644
--- a/library/src/layout/align.rs
+++ b/library/src/layout/align.rs
@@ -2,7 +2,14 @@ use crate::prelude::*;
 
 /// Align content horizontally and vertically.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional, required)
+///   The content to align.
+/// - alignment: Axes<Option<GenAlign>> (positional, settable)
+///   The alignment along both axes.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/columns.rs b/library/src/layout/columns.rs
index 3bbf56e4..b31b0a6d 100644
--- a/library/src/layout/columns.rs
+++ b/library/src/layout/columns.rs
@@ -3,13 +3,20 @@ use crate::text::TextNode;
 
 /// Separate a region into multiple equally sized columns.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - count: usize (positional, required)
+///   The number of columns.
+/// - body: Content (positional, required)
+///   The content that should be layouted into the columns.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout)]
 #[derive(Debug, Hash)]
 pub struct ColumnsNode {
     /// How many columns there should be.
-    pub columns: NonZeroUsize,
+    pub count: NonZeroUsize,
     /// The child to be layouted into the columns. Most likely, this should be a
     /// flow or stack node.
     pub body: Content,
@@ -23,7 +30,7 @@ impl ColumnsNode {
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {
         Ok(Self {
-            columns: args.expect("column count")?,
+            count: args.expect("column count")?,
             body: args.expect("body")?,
         }
         .pack())
@@ -44,7 +51,7 @@ impl Layout for ColumnsNode {
         }
 
         // Determine the width of the gutter and each column.
-        let columns = self.columns.get();
+        let columns = self.count.get();
         let gutter = styles.get(Self::GUTTER).relative_to(regions.base.x);
         let width = (regions.first.x - gutter * (columns - 1) as f64) / columns as f64;
 
@@ -106,7 +113,13 @@ impl Layout for ColumnsNode {
 
 /// A column break.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - weak: bool (named)
+///   If true, the column break is skipped if the current column is already
+///   empty.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Behave)]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/container.rs b/library/src/layout/container.rs
index d451bccf..4b58434b 100644
--- a/library/src/layout/container.rs
+++ b/library/src/layout/container.rs
@@ -1,9 +1,19 @@
 use super::VNode;
+use crate::layout::Spacing;
 use crate::prelude::*;
 
 /// An inline-level container that sizes content.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional)
+///   The contents of the box.
+/// - width: Rel<Length> (named)
+///   The width of the box.
+/// - height: Rel<Length> (named)
+///   The height of the box.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout, Inline)]
 #[derive(Debug, Hash)]
@@ -65,7 +75,20 @@ impl Inline for BoxNode {}
 
 /// A block-level container that places content into a separate flow.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional)
+///   The contents of the block.
+/// - spacing: Spacing (named, settable)
+///   The spacing around this block.
+/// - above: Spacing (named, settable)
+///   The spacing between the previous and this block. Takes precedence over
+///   `spacing`.
+/// - below: Spacing (named, settable)
+///   The spacing between this block and the following one. Takes precedence
+///   over `spacing`.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout)]
 #[derive(Debug, Hash)]
@@ -74,10 +97,10 @@ pub struct BlockNode(pub Content);
 #[node]
 impl BlockNode {
     /// The spacing between the previous and this block.
-    #[property(reflect, skip)]
+    #[property(skip)]
     pub const ABOVE: VNode = VNode::block_spacing(Em::new(1.2).into());
     /// The spacing between this and the following block.
-    #[property(reflect, skip)]
+    #[property(skip)]
     pub const BELOW: VNode = VNode::block_spacing(Em::new(1.2).into());
     /// Whether this block must stick to the following one.
     #[property(skip)]
diff --git a/library/src/layout/grid.rs b/library/src/layout/grid.rs
index e70210c0..8aaffe08 100644
--- a/library/src/layout/grid.rs
+++ b/library/src/layout/grid.rs
@@ -4,7 +4,22 @@ use super::Spacing;
 
 /// Arrange content in a grid.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - cells: Content (positional, variadic)
+///   The contents of the table cells.
+/// - rows: TrackSizings (named)
+///   Defines the row sizes.
+/// - columns: TrackSizings (named)
+///   Defines the column sizes.
+/// - gutter: TrackSizings (named)
+///   Defines the gaps between rows & columns.
+/// - column-gutter: TrackSizings (named)
+///   Defines the gaps between columns. Takes precedence over `gutter`.
+/// - row-gutter: TrackSizings (named)
+///   Defines the gaps between rows. Takes precedence over `gutter`.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout)]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/hide.rs b/library/src/layout/hide.rs
index 4e70dca9..fc9150c1 100644
--- a/library/src/layout/hide.rs
+++ b/library/src/layout/hide.rs
@@ -2,7 +2,12 @@ use crate::prelude::*;
 
 /// Hide content without affecting layout.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional, required)
+///   The content to hide.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout, Inline)]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/pad.rs b/library/src/layout/pad.rs
index 9d882ba4..94492f83 100644
--- a/library/src/layout/pad.rs
+++ b/library/src/layout/pad.rs
@@ -2,7 +2,26 @@ use crate::prelude::*;
 
 /// Pad content at the sides.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional, required)
+///   The content to pad at the sides.
+/// - left: Rel<Length> (named)
+///   The padding at the left side.
+/// - right: Rel<Length> (named)
+///   The padding at the right side.
+/// - top: Rel<Length> (named)
+///   The padding at the top side.
+/// - bottom: Rel<Length> (named)
+///   The padding at the bottom side.
+/// - x: Rel<Length> (named)
+///   The horizontal padding. Both `left` and `right` take precedence over this.
+/// - y: Rel<Length> (named)
+///   The vertical padding. Both `top` and `bottom` take precedence over this.
+/// - rest: Rel<Length> (named)
+///   The padding for all sides. All other parameters take precedence over this.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout)]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/page.rs b/library/src/layout/page.rs
index fe83137e..8782ed08 100644
--- a/library/src/layout/page.rs
+++ b/library/src/layout/page.rs
@@ -6,7 +6,14 @@ use crate::text::TextNode;
 
 /// Layouts its child onto one or multiple pages.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional, required)
+///   The contents of the page(s).
+/// - paper: Paper (positional, settable)
+///   The paper size.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable]
 #[derive(Clone, Hash)]
@@ -14,9 +21,6 @@ pub struct PageNode(pub Content);
 
 #[node]
 impl PageNode {
-    /// The paper size.
-    #[property(reflect, skip, shorthand)]
-    pub const PAPER: Paper = Paper::A4;
     /// The unflipped width of the page.
     #[property(resolve)]
     pub const WIDTH: Smart<Length> = Smart::Custom(Paper::A4.width().into());
@@ -91,7 +95,7 @@ impl PageNode {
         // Realize columns.
         let columns = styles.get(Self::COLUMNS);
         if columns.get() > 1 {
-            child = ColumnsNode { columns, body: self.0.clone() }.pack();
+            child = ColumnsNode { count: columns, body: self.0.clone() }.pack();
         }
 
         // Realize margins.
@@ -151,7 +155,12 @@ impl Debug for PageNode {
 
 /// A page break.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - weak: bool (named)
+///   If true, the page break is skipped if the current page is already empty.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable]
 #[derive(Debug, Copy, Clone, Hash)]
@@ -266,7 +275,10 @@ macro_rules! papers {
 
         castable! {
             Paper,
-            $($pat => Self::$var,)*
+            $(
+                /// Produces a paper of the respective size.
+                $pat => Self::$var,
+            )*
         }
     };
 }
diff --git a/library/src/layout/par.rs b/library/src/layout/par.rs
index eed0dbb1..f9731ff2 100644
--- a/library/src/layout/par.rs
+++ b/library/src/layout/par.rs
@@ -13,7 +13,12 @@ use crate::text::{
 
 /// Arrange text, spacing and inline-level nodes into a paragraph.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional, required)
+///   The contents of the paragraph.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable]
 #[derive(Hash)]
@@ -144,7 +149,8 @@ castable! {
 
 /// A paragraph break.
 ///
-/// Tags: layout.
+/// # Tags
+/// - layout
 #[func]
 #[capable(Unlabellable)]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/place.rs b/library/src/layout/place.rs
index c3fcd0d5..890480a7 100644
--- a/library/src/layout/place.rs
+++ b/library/src/layout/place.rs
@@ -2,7 +2,18 @@ use crate::prelude::*;
 
 /// Place content at an absolute position.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - alignment: Axes<Option<GenAlign>> (positional)
+///   Relative to which position in the parent container to place the content.
+/// - body: Content (positional, required)
+///   The content to place.
+/// - dx: Rel<Length> (named)
+///   The horizontal displacement of the placed content.
+/// - dy: Rel<Length> (named)
+///   The vertical displacement of the placed content.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout, Behave)]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/repeat.rs b/library/src/layout/repeat.rs
index a47dbb3e..fa87d922 100644
--- a/library/src/layout/repeat.rs
+++ b/library/src/layout/repeat.rs
@@ -2,7 +2,12 @@ use crate::prelude::*;
 
 /// Repeats content to fill a line.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional, required)
+///   The content to repeat.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout, Inline)]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/spacing.rs b/library/src/layout/spacing.rs
index e961c0cf..ef69c070 100644
--- a/library/src/layout/spacing.rs
+++ b/library/src/layout/spacing.rs
@@ -2,9 +2,18 @@ use std::cmp::Ordering;
 
 use crate::prelude::*;
 
-/// Horizontal spacing.
+/// Horizontal spacing in a paragraph.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - amount: Spacing (positional, required)
+///   How much spacing to insert.
+/// - weak: bool (named)
+///   If true, the spacing collapses at the start or end of a paragraph.
+///   Moreover, from multiple adjacent weak spacings all but the largest one
+///   collapse.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Behave)]
 #[derive(Debug, Copy, Clone, Hash)]
@@ -55,7 +64,16 @@ impl Behave for HNode {
 
 /// Vertical spacing.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - amount: Spacing (positional, required)
+///   How much spacing to insert.
+/// - weak: bool (named)
+///   If true, the spacing collapses at the start or end of a flow.
+///   Moreover, from multiple adjacent weak spacings all but the largest one
+///   collapse.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Behave)]
 #[derive(Debug, Copy, Clone, Hash, PartialEq, PartialOrd)]
@@ -123,11 +141,6 @@ impl Behave for VNode {
     }
 }
 
-castable! {
-    VNode,
-    spacing: Spacing => VNode::block_around(spacing),
-}
-
 /// Kinds of spacing.
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
 pub enum Spacing {
diff --git a/library/src/layout/stack.rs b/library/src/layout/stack.rs
index 111e3433..deb565b6 100644
--- a/library/src/layout/stack.rs
+++ b/library/src/layout/stack.rs
@@ -5,7 +5,16 @@ use crate::prelude::*;
 
 /// Arrange content and spacing along an axis.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - items: StackChild (positional, variadic)
+///   The items to stack along an axis.
+/// - dir: Dir (named)
+///   The direction along which the items are stacked.
+/// - spacing: Spacing (named)
+///   Spacing to insert between items where no explicit spacing was provided.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout)]
 #[derive(Debug, Hash)]
diff --git a/library/src/layout/transform.rs b/library/src/layout/transform.rs
index f1a89d4c..3af44ca0 100644
--- a/library/src/layout/transform.rs
+++ b/library/src/layout/transform.rs
@@ -4,7 +4,16 @@ use crate::prelude::*;
 
 /// Move content without affecting layout.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional, required)
+///   The content to move.
+/// - dx: Rel<Length> (named)
+///   The horizontal displacement of the content.
+/// - dy: Rel<Length> (named)
+///   The vertical displacement of the content.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout, Inline)]
 #[derive(Debug, Hash)]
@@ -49,7 +58,18 @@ impl Inline for MoveNode {}
 
 /// Transform content without affecting layout.
 ///
-/// Tags: layout.
+/// # Parameters
+/// - body: Content (positional, required)
+///   The content to transform.
+/// - angle: Angle (named)
+///   The amount of rotation.
+/// - x: Ratio (named)
+///   The horizontal scaling factor.
+/// - y: Ratio (named)
+///   The vertical scaling factor.
+///
+/// # Tags
+/// - layout
 #[func]
 #[capable(Layout, Inline)]
 #[derive(Debug, Hash)]