Documentation for measure, locate, and style

3 files changed, 74 insertions, 26 deletions

diff --git a/library/src/layout/measure.rs b/library/src/layout/measure.rs
index df66d67f..3bd11ce6 100644
--- a/library/src/layout/measure.rs
+++ b/library/src/layout/measure.rs
@@ -1,10 +1,39 @@
 use crate::prelude::*;
 
-/// Measure the size of content.
+/// Measure the layouted size of content.
+///
+/// The `measure` function lets you determine the layouted size of content.
+/// The same content can have a different size depending on the styles that
+/// are active when it is layouted. For example, in the example below
+/// `[#content]` is of course bigger when we increase the font size.
+///
+/// ```example
+/// #let content = [Hello!]
+/// #content
+/// #set text(14pt)
+/// #content
+/// ```
+///
+/// To do a meaningful measurement, you therefore first need to retrieve the
+/// active styles with the [`style`]($func/style) function. You can then pass
+/// them to the `measure` function.
+///
+/// ```example
+/// #let thing(body) = style(styles => {
+///   let size = measure(body, styles)
+///   [Width of "#body" is #size.width]
+/// })
+///
+/// #thing[Hey] \
+/// #thing[Welcome]
+/// ```
+///
+/// The measure function returns a dictionary with the entries `width` and
+/// `height`, both of type [`length`]($type/length).
 ///
 /// Display: Measure
 /// Category: layout
-/// Returns: array
+/// Returns: dictionary
 #[func]
 pub fn measure(
     /// The content whose size to measure.
@@ -16,5 +45,5 @@ pub fn measure(
     let styles = StyleChain::new(&styles);
     let frame = content.measure(&mut vm.vt, styles, pod)?.into_frame();
     let Size { x, y } = frame.size();
-    Value::Array(array![x, y])
+    dict! { "width" => x, "height" => y }.into()
 }
diff --git a/library/src/meta/context.rs b/library/src/meta/context.rs
index dbb84812..376456b8 100644
--- a/library/src/meta/context.rs
+++ b/library/src/meta/context.rs
@@ -1,13 +1,22 @@
 use crate::prelude::*;
 
-/// Provide access to the location of content.
+/// Provides access to the location of content.
+///
+/// This is useful in combination with [queries]($func/query),
+/// [counters]($func/counter), [state]($func/state), and [links]($func/link).
+/// See their documentation for more details.
 ///
 /// Display: Locate
 /// Category: meta
 /// Returns: content
 #[func]
 pub fn locate(
-    /// The function to call with the location.
+    /// A function that receives a `location`. Its return value is displayed
+    /// in the document.
+    ///
+    /// This function is called once for each time the content returned by
+    /// `locate` appears in the document. That makes it possible to generate
+    /// content that depends on its own location in the document.
     func: Func,
 ) -> Value {
     LocateElem::new(func).pack().into()
@@ -15,7 +24,7 @@ pub fn locate(
 
 /// Executes a `locate` call.
 ///
-/// Display: Styled
+/// Display: Locate
 /// Category: special
 #[element(Locatable, Show)]
 struct LocateElem {
@@ -35,14 +44,24 @@ impl Show for LocateElem {
     }
 }
 
-/// Provide access to active styles.
+/// Provides access to active styles.
+///
+/// The styles are currently opaque and only useful in combination with the
+/// [`measure`]($func/measure) function. See its documentation for more details.
+/// In the future, the provided styles might also be directly accessed to look
+/// up styles defined by [set rules]($styling/#set-rules).
 ///
-/// Display: Styled
-/// Category: layout
+/// Display: Style
+/// Category: meta
 /// Returns: content
 #[func]
 pub fn style(
-    /// The function to call with the styles.
+    /// A function to call with the styles. Its return value is displayed
+    /// in the document.
+    ///
+    /// This function is called once for each time the content returned by
+    /// `style` appears in the document. That makes it possible to generate
+    /// content that depends on the style context it appears in.
     func: Func,
 ) -> Value {
     StyleElem::new(func).pack().into()
diff --git a/library/src/meta/state.rs b/library/src/meta/state.rs
index 29f4bf0d..11073594 100644
--- a/library/src/meta/state.rs
+++ b/library/src/meta/state.rs
@@ -20,12 +20,12 @@ use crate::prelude::*;
 ///   x = eval(
 ///     expr.replace("x", str(x))
 ///   )
-///   [New value is #x. \ ]
+///   [New value is #x. ]
 /// }
 ///
-/// #compute("10")
-/// #compute("x + 3")
-/// #compute("x * 2")
+/// #compute("10") \
+/// #compute("x + 3") \
+/// #compute("x * 2") \
 /// #compute("x - 5")
 /// ```
 ///
@@ -83,12 +83,12 @@ use crate::prelude::*;
 ///   #s.update(x =>
 ///     eval(expr.replace("x", str(x)))
 ///   )
-///   New value is #s.display(). \
+///   New value is #s.display().
 /// ]
 ///
-/// #compute("10")
-/// #compute("x + 3")
-/// #compute("x * 2")
+/// #compute("10") \
+/// #compute("x + 3") \
+/// #compute("x * 2") \
 /// #compute("x - 5")
 /// ```
 ///
@@ -105,17 +105,17 @@ use crate::prelude::*;
 /// >>>   #s.update(x =>
 /// >>>     eval(expr.replace("x", str(x)))
 /// >>>   )
-/// >>>   New value is #s.display(). \
+/// >>>   New value is #s.display().
 /// >>> ]
 /// <<< ...
 ///
 /// #let more = [
-///   #compute("x * 2")
+///   #compute("x * 2") \
 ///   #compute("x - 5")
 /// ]
 ///
-/// #compute("10")
-/// #compute("x + 3")
+/// #compute("10") \
+/// #compute("x + 3") \
 /// #more
 /// ```
 ///
@@ -137,7 +137,7 @@ use crate::prelude::*;
 /// >>>   #s.update(x => {
 /// >>>     eval(expr.replace("x", str(x)))
 /// >>>   })
-/// >>>   New value is #s.display(). \
+/// >>>   New value is #s.display().
 /// >>> ]
 /// <<< ...
 ///
@@ -148,10 +148,10 @@ use crate::prelude::*;
 ///     .location()
 /// ))
 ///
-/// #compute("10")
-/// #compute("x + 3")
+/// #compute("10") \
+/// #compute("x + 3") \
 /// *Here.* <here> \
-/// #compute("x * 2")
+/// #compute("x * 2") \
 /// #compute("x - 5")
 /// ```
 ///