diff --git a/crates/typst-library/src/foundations/ty.rs b/crates/typst-library/src/foundations/ty.rs
index 40f7003c3..19aa4a7ac 100644
--- a/crates/typst-library/src/foundations/ty.rs
+++ b/crates/typst-library/src/foundations/ty.rs
@@ -44,6 +44,22 @@ use crate::foundations::{
 /// #type(int) \
 /// #type(type)
 /// ```
+///
+/// [none]($none) and [auto]($auto) are more special. Because they are the only
+/// values of their type, their type isn't actually bound to any name.
+/// ```example
+/// type(none) == none: #{ type(none) == none } \
+/// type(auto) == auto: #{ type(auto) == auto }
+/// ```
+/// Instead, to test for these _values_, compare to them directly:
+/// ```example
+/// #let empty = none
+/// empty is none: #{ empty == none }
+/// ```
+///
+/// Note that `type` is used for "high level" comparisons, such as whether a variable is `content`
+/// vs `int`. See [func]($content.func) to programmatically determine which _element_ a variable
+/// is.
 #[ty(scope, cast)]
 #[derive(Copy, Clone, Eq, PartialEq, Hash)]
 pub struct Type(Static<NativeTypeData>);