Touch up docs a little

3 files changed, 47 insertions, 14 deletions

diff --git a/crates/typst-docs/src/link.rs b/crates/typst-docs/src/link.rs
index 5d7a5485..64fb47f9 100644
--- a/crates/typst-docs/src/link.rs
+++ b/crates/typst-docs/src/link.rs
@@ -37,16 +37,16 @@ fn split_link(link: &str) -> StrResult<(&str, &str)> {
 /// Resolve a `$` link head to a known destination.
 fn resolve_known(head: &str) -> Option<&'static str> {
     Some(match head {
-        "$tutorial" => "/docs/tutorial/",
-        "$reference" => "/docs/reference/",
-        "$category" => "/docs/reference/",
-        "$syntax" => "/docs/reference/syntax/",
-        "$styling" => "/docs/reference/styling/",
-        "$scripting" => "/docs/reference/scripting/",
-        "$guides" => "/docs/guides/",
-        "$packages" => "/docs/packages/",
-        "$changelog" => "/docs/changelog/",
-        "$community" => "/docs/community/",
+        "$tutorial" => "/docs/tutorial",
+        "$reference" => "/docs/reference",
+        "$category" => "/docs/reference",
+        "$syntax" => "/docs/reference/syntax",
+        "$styling" => "/docs/reference/styling",
+        "$scripting" => "/docs/reference/scripting",
+        "$guides" => "/docs/guides",
+        "$packages" => "/docs/packages",
+        "$changelog" => "/docs/changelog",
+        "$community" => "/docs/community",
         _ => return None,
     })
 }
diff --git a/crates/typst/src/eval/array.rs b/crates/typst/src/eval/array.rs
index cb9234b3..90f59b2f 100644
--- a/crates/typst/src/eval/array.rs
+++ b/crates/typst/src/eval/array.rs
@@ -648,7 +648,7 @@ impl Array {
         /// A value to insert between each item of the array.
         #[default]
         separator: Option<Value>,
-        /// An alternative separator between the last two items
+        /// An alternative separator between the last two items.
         #[named]
         last: Option<Value>,
     ) -> StrResult<Value> {
@@ -675,7 +675,11 @@ impl Array {
     /// Returns an array with a copy of the separator value placed between
     /// adjacent elements.
     #[func]
-    pub fn intersperse(&self, sep: Value) -> Array {
+    pub fn intersperse(
+        &self,
+        /// The value that will be placed between each adjacent element.
+        separator: Value,
+    ) -> Array {
         // TODO: Use once stabilized:
         // https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.intersperse
         let size = match self.len() {
@@ -690,7 +694,7 @@ impl Array {
         }
 
         for value in iter {
-            vec.push(sep.clone());
+            vec.push(separator.clone());
             vec.push(value);
         }
 
diff --git a/crates/typst/src/eval/ty.rs b/crates/typst/src/eval/ty.rs
index da3c91aa..5a2457e6 100644
--- a/crates/typst/src/eval/ty.rs
+++ b/crates/typst/src/eval/ty.rs
@@ -18,11 +18,40 @@ pub use typst_macros::{scope, ty};
 /// shapes, and more. Typst categorizes these into clearly defined _types_ and
 /// tells you where it expects which type of value.
 ///
-/// Apart from very basic types for numeric values and [typical]($int)
+/// Apart from basic types for numeric values and [typical]($int)
 /// [types]($float) [known]($str) [from]($array) [programming]($dictionary)
 /// languages, Typst provides a special type for [_content._]($content) A value
 /// of this type can hold anything that you can enter into your document: Text,
 /// elements like headings and shapes, and style information.
+///
+/// # Example
+/// ```example
+/// #let x = 10
+/// #if type(x) == int [
+///   #x is an integer!
+/// ] else [
+///   #x is another value...
+/// ]
+///
+/// An image is of type
+/// #type(image("glacier.jpg")).
+/// ```
+///
+/// The type of `10` is `int`. Now, what is the type of `int` or even `type`?
+/// ```example
+/// #type(int) \
+/// #type(type)
+/// ```
+///
+/// # Compatibility
+/// In Typst 0.7 and lower, the `type` function returned a string instead of a
+/// type. Compatibility with the old way will remain for a while to give package
+/// authors time to upgrade, but it will be removed at some point.
+///
+/// - Checks like `{int == "integer"}` evaluate to `{true}`
+/// - Adding/joining a type and string will yield a string
+/// - The `{in}` operator on a type and a dictionary will evaluate to `{true}`
+///   if the dictionary has a string key matching the type's name
 #[ty(scope)]
 #[derive(Copy, Clone, Eq, PartialEq, Hash)]
 pub struct Type(Static<NativeTypeData>);