diff --git a/crates/typst-library/src/foundations/array.rs b/crates/typst-library/src/foundations/array.rs
index 340c3adc7..6ebfc6a1f 100644
--- a/crates/typst-library/src/foundations/array.rs
+++ b/crates/typst-library/src/foundations/array.rs
@@ -838,16 +838,30 @@ impl Array {
         /// The callsite span.
         span: Span,
         /// If given, applies this function to the elements in the array to
-        /// determine the keys to sort by. Mutually exclusive with `compare`.
+        /// determine the keys to sort by.
         #[named]
         key: Option<Func>,
         /// If given, uses this function to compare elements in the array.
-        /// Mutually exclusive with `key`.
         ///
         /// This function should return an integer, whose sign is used to
         /// determine the relative order of two given elements: Negative if the
         /// first element is smaller, positive if the second element is smaller.
         /// If `{0}` is returned, the order of the elements is not modified.
+        ///
+        /// When used together with `key`, `compare` will be passed the keys
+        /// instead of the elements.
+        ///
+        /// ```example
+        /// #(
+        ///   "sorted",
+        ///   "by",
+        ///   "decreasing",
+        ///   "length",
+        /// ).sorted(
+        ///   key: s => s.len(),
+        ///   compare: (x, y) => y - x,
+        /// )
+        /// ```
         #[named]
         compare: Option<Func>,
     ) -> SourceResult<Array> {