Deprecate some things (#4562)

6 files changed, 71 insertions, 20 deletions

diff --git a/crates/typst/src/foundations/styles.rs b/crates/typst/src/foundations/styles.rs
index 42be8922..48009c8c 100644
--- a/crates/typst/src/foundations/styles.rs
+++ b/crates/typst/src/foundations/styles.rs
@@ -7,7 +7,7 @@ use comemo::{Track, Tracked};
 use ecow::{eco_vec, EcoString, EcoVec};
 use smallvec::SmallVec;
 
-use crate::diag::{SourceResult, Trace, Tracepoint};
+use crate::diag::{warning, SourceResult, Trace, Tracepoint};
 use crate::engine::Engine;
 use crate::foundations::{
     cast, elem, func, ty, Content, Context, Element, Func, NativeElement, Packed, Repr,
@@ -33,6 +33,8 @@ use crate::utils::LazyHash;
 /// ```
 #[func]
 pub fn style(
+    /// The engine.
+    engine: &mut Engine,
     /// The call site span.
     span: Span,
     /// A function to call with the styles. Its return value is displayed
@@ -43,6 +45,11 @@ pub fn style(
     /// content that depends on the style context it appears in.
     func: Func,
 ) -> Content {
+    engine.sink.warn(warning!(
+        span, "`style` is deprecated";
+        hint: "use a `context` expression instead"
+    ));
+
     StyleElem::new(func).pack().spanned(span)
 }
 
diff --git a/crates/typst/src/introspection/counter.rs b/crates/typst/src/introspection/counter.rs
index 13ea4d14..2aefb68e 100644
--- a/crates/typst/src/introspection/counter.rs
+++ b/crates/typst/src/introspection/counter.rs
@@ -5,7 +5,7 @@ use comemo::{Track, Tracked, TrackedMut};
 use ecow::{eco_format, eco_vec, EcoString, EcoVec};
 use smallvec::{smallvec, SmallVec};
 
-use crate::diag::{bail, At, HintedStrResult, SourceResult};
+use crate::diag::{bail, warning, At, HintedStrResult, SourceResult};
 use crate::engine::{Engine, Route, Sink, Traced};
 use crate::foundations::{
     cast, elem, func, scope, select_where, ty, Args, Array, Construct, Content, Context,
@@ -464,6 +464,11 @@ impl Counter {
         if let Ok(loc) = context.location() {
             self.display_impl(engine, loc, numbering, both, context.styles().ok())
         } else {
+            engine.sink.warn(warning!(
+                span, "`counter.display` without context is deprecated";
+                hint: "use it in a `context` expression instead"
+            ));
+
             Ok(CounterDisplayElem::new(self, numbering, both)
                 .pack()
                 .spanned(span)
@@ -508,13 +513,19 @@ impl Counter {
         context: Tracked<Context>,
         /// The callsite span.
         span: Span,
-        /// _Compatibility:_ This argument only exists for compatibility with
-        /// Typst 0.10 and lower and shouldn't be used anymore.
+        /// _Compatibility:_ This argument is deprecated. It only exists for
+        /// compatibility with Typst 0.10 and lower and shouldn't be used
+        /// anymore.
         #[default]
         location: Option<Location>,
     ) -> SourceResult<CounterState> {
         if location.is_none() {
             context.location().at(span)?;
+        } else {
+            engine.sink.warn(warning!(
+                span, "calling `counter.final` with a location is deprecated";
+                hint: "try removing the location argument"
+            ));
         }
 
         let sequence = self.sequence(engine)?;
diff --git a/crates/typst/src/introspection/locate.rs b/crates/typst/src/introspection/locate.rs
index 373b1fe2..8991ae9b 100644
--- a/crates/typst/src/introspection/locate.rs
+++ b/crates/typst/src/introspection/locate.rs
@@ -1,6 +1,6 @@
 use comemo::{Track, Tracked};
 
-use crate::diag::{HintedStrResult, SourceResult};
+use crate::diag::{warning, HintedStrResult, SourceResult};
 use crate::engine::Engine;
 use crate::foundations::{
     cast, elem, func, Content, Context, Func, LocatableSelector, NativeElement, Packed,
@@ -29,11 +29,12 @@ use crate::syntax::Span;
 ///
 /// # Compatibility
 /// In Typst 0.10 and lower, the `locate` function took a closure that made the
-/// current location in the document available (like [`here`] does now).
-/// Compatibility with the old way will remain for a while to give package
-/// authors time to upgrade. To that effect, `locate` detects whether it
-/// received a selector or a user-defined function and adjusts its semantics
-/// accordingly. This behaviour will be removed in the future.
+/// current location in the document available (like [`here`] does now). This
+/// usage pattern is deprecated. Compatibility with the old way will remain for
+/// a while to give package authors time to upgrade. To that effect, `locate`
+/// detects whether it received a selector or a user-defined function and
+/// adjusts its semantics accordingly. This behaviour will be removed in the
+/// future.
 #[func(contextual)]
 pub fn locate(
     /// The engine.
@@ -56,6 +57,11 @@ pub fn locate(
             LocateOutput::Location(selector.resolve_unique(engine.introspector, context)?)
         }
         LocateInput::Func(func) => {
+            engine.sink.warn(warning!(
+                span, "`locate` with callback function is deprecated";
+                hint: "use a `context` expression instead"
+            ));
+
             LocateOutput::Content(LocateElem::new(func).pack().spanned(span))
         }
     })
diff --git a/crates/typst/src/introspection/query.rs b/crates/typst/src/introspection/query.rs
index e416bfc9..07f761a8 100644
--- a/crates/typst/src/introspection/query.rs
+++ b/crates/typst/src/introspection/query.rs
@@ -1,9 +1,10 @@
 use comemo::Tracked;
 
-use crate::diag::HintedStrResult;
+use crate::diag::{warning, HintedStrResult};
 use crate::engine::Engine;
 use crate::foundations::{func, Array, Context, LocatableSelector, Value};
 use crate::introspection::Location;
+use crate::syntax::Span;
 
 /// Finds elements in the document.
 ///
@@ -141,6 +142,8 @@ pub fn query(
     engine: &mut Engine,
     /// The callsite context.
     context: Tracked<Context>,
+    /// The span of the `query` call.
+    span: Span,
     /// Can be
     /// - an element function like a `heading` or `figure`,
     /// - a `{<label>}`,
@@ -149,13 +152,18 @@ pub fn query(
     ///
     /// Only [locatable]($location/#locatable) element functions are supported.
     target: LocatableSelector,
-    /// _Compatibility:_ This argument only exists for compatibility with
-    /// Typst 0.10 and lower and shouldn't be used anymore.
+    /// _Compatibility:_ This argument is deprecated. It only exists for
+    /// compatibility with Typst 0.10 and lower and shouldn't be used anymore.
     #[default]
     location: Option<Location>,
 ) -> HintedStrResult<Array> {
     if location.is_none() {
         context.introspect()?;
+    } else {
+        engine.sink.warn(warning!(
+            span, "calling `query` with a location is deprecated";
+            hint: "try removing the location argument"
+        ));
     }
 
     let vec = engine.introspector.query(&target.0);
diff --git a/crates/typst/src/introspection/state.rs b/crates/typst/src/introspection/state.rs
index be114c86..a88ed526 100644
--- a/crates/typst/src/introspection/state.rs
+++ b/crates/typst/src/introspection/state.rs
@@ -1,7 +1,7 @@
 use comemo::{Track, Tracked, TrackedMut};
 use ecow::{eco_format, eco_vec, EcoString, EcoVec};
 
-use crate::diag::{bail, At, SourceResult};
+use crate::diag::{bail, warning, At, SourceResult};
 use crate::engine::{Engine, Route, Sink, Traced};
 use crate::foundations::{
     cast, elem, func, scope, select_where, ty, Args, Construct, Content, Context, Func,
@@ -325,13 +325,19 @@ impl State {
         context: Tracked<Context>,
         /// The callsite span.
         span: Span,
-        /// _Compatibility:_ This argument only exists for compatibility with
-        /// Typst 0.10 and lower and shouldn't be used anymore.
+        /// _Compatibility:_ This argument is deprecated. It only exists for
+        /// compatibility with Typst 0.10 and lower and shouldn't be used
+        /// anymore.
         #[default]
         location: Option<Location>,
     ) -> SourceResult<Value> {
         if location.is_none() {
             context.location().at(span)?;
+        } else {
+            engine.sink.warn(warning!(
+                span, "calling `state.final` with a location is deprecated";
+                hint: "try removing the location argument"
+            ));
         }
 
         let sequence = self.sequence(engine)?;
@@ -365,6 +371,8 @@ impl State {
     #[func]
     pub fn display(
         self,
+        /// The engine.
+        engine: &mut Engine,
         /// The span of the `display` call.
         span: Span,
         /// A function which receives the value of the state and can return
@@ -373,6 +381,11 @@ impl State {
         #[default]
         func: Option<Func>,
     ) -> Content {
+        engine.sink.warn(warning!(
+            span, "`state.display` is deprecated";
+            hint: "use `state.get` in a `context` expression instead"
+        ));
+
         StateDisplayElem::new(self, func).pack().spanned(span)
     }
 }
diff --git a/crates/typst/src/layout/measure.rs b/crates/typst/src/layout/measure.rs
index af093f24..cb08e591 100644
--- a/crates/typst/src/layout/measure.rs
+++ b/crates/typst/src/layout/measure.rs
@@ -1,6 +1,6 @@
 use comemo::Tracked;
 
-use crate::diag::{At, SourceResult};
+use crate::diag::{warning, At, SourceResult};
 use crate::engine::Engine;
 use crate::foundations::{
     dict, func, Content, Context, Dict, Resolve, Smart, StyleChain, Styles,
@@ -76,13 +76,19 @@ pub fn measure(
     height: Smart<Length>,
     /// The content whose size to measure.
     content: Content,
-    /// _Compatibility:_ This argument only exists for compatibility with
-    /// Typst 0.10 and lower and shouldn't be used anymore.
+    /// _Compatibility:_ This argument is deprecated. It only exists for
+    /// compatibility with Typst 0.10 and lower and shouldn't be used anymore.
     #[default]
     styles: Option<Styles>,
 ) -> SourceResult<Dict> {
     let styles = match &styles {
-        Some(styles) => StyleChain::new(styles),
+        Some(styles) => {
+            engine.sink.warn(warning!(
+                span, "calling `measure` with a styles argument is deprecated";
+                hint: "try removing the styles argument"
+            ));
+            StyleChain::new(styles)
+        }
         None => context.styles().at(span)?,
     };