Mark TimeSeriesScalar as deprecated in all SDKs and documentation

crates/re_data_store/benches/gc.rs

@@ -81,9 +81,8 @@ fn plotting_dashboard(c: &mut Criterion) {
         .into()
     };
 
-    let mut datagen = |i| {
-        Box::new(re_types::archetypes::TimeSeriesScalar::new(i as f64)) as Box<dyn AsComponents>
-    };
+    let mut datagen =
+        |i| Box::new(re_types::archetypes::Scalar::new(i as f64)) as Box<dyn AsComponents>;
 
     // Default config
     group.bench_function("default", |b| {

crates/re_space_view_time_series/src/legacy_visualizer_system.rs

@@ -1,7 +1,6 @@
 use itertools::Itertools;
 use re_query_cache::QueryError;
 use re_types::{
-    archetypes::TimeSeriesScalar,
     components::{Color, Radius, Scalar, ScalarScattering, Text},
     Archetype, Loggable,
 };
@@ -16,6 +15,9 @@ use crate::{
     PlotPoint, PlotPointAttrs, PlotSeries, PlotSeriesKind, ScatterAttrs,
 };
 
+#[allow(deprecated)]
+use re_types::archetypes::TimeSeriesScalar;
+
 /// The legacy system for rendering [`TimeSeriesScalar`] archetypes.
 #[derive(Default, Debug)]
 pub struct LegacyTimeSeriesSystem {
@@ -30,6 +32,7 @@ impl IdentifiedViewSystem for LegacyTimeSeriesSystem {
 }
 
 impl VisualizerSystem for LegacyTimeSeriesSystem {
+    #[allow(deprecated)]
     fn visualizer_query_info(&self) -> VisualizerQueryInfo {
         let mut query_info = VisualizerQueryInfo::from_archetype::<TimeSeriesScalar>();
         // Although we don't normally include indicator components in required components,
@@ -85,6 +88,7 @@ impl VisualizerSystem for LegacyTimeSeriesSystem {
 }
 
 impl LegacyTimeSeriesSystem {
+    #[allow(deprecated)]
     fn load_scalars(
         &mut self,
         ctx: &ViewerContext<'_>,

crates/re_types/definitions/rerun/archetypes/time_series_scalar.fbs

@@ -1,5 +1,6 @@
 include "fbs/attributes.fbs";
 
+include "rerun/attributes.fbs";
 include "rerun/datatypes.fbs";
 include "rerun/components.fbs";
 
@@ -22,6 +23,7 @@ namespace rerun.archetypes;
 /// \example scalar_simple title="Simple line plot" image="https://static.rerun.io/scalar_simple/8bcc92f56268739f8cd24d60d1fe72a655f62a46/1200w.png"
 /// \example scalar_multiple_plots !api title="Multiple time series plots" image="https://static.rerun.io/scalar_multiple/15845c2a348f875248fbd694e03eabd922741c4c/1200w.png"
 table TimeSeriesScalar (
+  "attr.rerun.deprecated": "Use the `Scalar` + (optional) `SeriesLine`/`SeriesPoint` archetypes instead, logged on the same entity.",
   "attr.rust.derive": "PartialEq"
 ) {
   // --- Required ---

crates/re_types/definitions/rerun/attributes.fbs

@@ -29,3 +29,13 @@ attribute "attr.rerun.override_type";
 ///
 /// This is used for example to scope blueprint types.
 attribute "attr.rerun.scope";
+
+/// Marks something as deprecated followed by a (non-optional!) migration note.
+///
+/// If specified on an object (struct/enum/union), it becomes deprecated such
+/// that using the object should emit a warning in all target languages.
+/// Furthermore, documentation will mention that the object is deprecated and display
+/// the specified migration note.
+///
+/// TODO(andreas): This is not yet supported on fields.
+attribute "attr.rerun.deprecated";

crates/re_types_builder/src/codegen/cpp/mod.rs

@@ -559,13 +559,27 @@ impl QuotedObject {
         let indicator_fqname =
             format!("{}Indicator", obj.fqname).replace("archetypes", "components");
         let doc_hide_comment = quote_hide_from_docs();
+        let deprecation_notice = quote_deprecation_notice(obj);
+        let (deprecation_ignore_start, deprecation_ignore_end) =
+            if obj.deprecation_notice().is_some() {
+                hpp_includes.insert_rerun("compiler_utils.hpp");
+                (
+                    quote! {
+                        RR_PUSH_WARNINGS #NEWLINE_TOKEN
+                        RR_DISABLE_DEPRECATION_WARNING #NEWLINE_TOKEN
+                    },
+                    quote! { RR_POP_WARNINGS },
+                )
+            } else {
+                (quote!(), quote!())
+            };
 
         let hpp = quote! {
             #hpp_includes
 
             namespace rerun::#quoted_namespace {
                 #quoted_docs
-                struct #type_ident {
+                struct #deprecation_notice #type_ident {
                     #(#field_declarations;)*
 
                 public:
@@ -594,17 +608,23 @@ impl QuotedObject {
                 template<typename T>
                 struct AsComponents;
 
+                #deprecation_ignore_start
+
                 #doc_hide_comment
                 template<>
                 struct AsComponents<#quoted_namespace::#type_ident> {
                     #serialize_hpp
                 };
+
+                #deprecation_ignore_end
             }
         };
 
         let cpp = quote! {
             #cpp_includes
 
+            #deprecation_ignore_start
+
             namespace rerun::#quoted_namespace {
                 #(#methods_cpp)*
             }
@@ -614,6 +634,8 @@ impl QuotedObject {
                 #NEWLINE_TOKEN
                 #serialize_cpp
             }
+
+            #deprecation_ignore_end
         };
 
         Self { hpp, cpp }
@@ -636,6 +658,7 @@ impl QuotedObject {
 
         let type_ident = obj.ident();
         let quoted_docs = quote_obj_docs(obj);
+        let deprecation_notice = quote_deprecation_notice(obj);
 
         let mut cpp_includes = Includes::new(obj.fqname.clone(), obj.scope());
         let mut hpp_declarations = ForwardDecls::default();
@@ -711,7 +734,7 @@ impl QuotedObject {
 
             namespace rerun::#quoted_namespace {
                 #quoted_docs
-                struct #type_ident {
+                struct #deprecation_notice #type_ident {
                     #(#field_declarations;)*
 
                     #hpp_type_extensions
@@ -780,6 +803,7 @@ impl QuotedObject {
         let pascal_case_name = &obj.name;
         let pascal_case_ident = obj.ident();
         let quoted_docs = quote_obj_docs(obj);
+        let deprecation_notice = quote_deprecation_notice(obj);
 
         let tag_typename = format_ident!("{pascal_case_name}Tag");
         let data_typename = format_ident!("{pascal_case_name}Data");
@@ -1068,7 +1092,7 @@ impl QuotedObject {
                 }
 
                 #quoted_docs
-                struct #pascal_case_ident {
+                struct #deprecation_notice #pascal_case_ident {
                     #pascal_case_ident() : _tag(detail::#tag_typename::None) {}
 
                     #copy_constructor
@@ -2296,3 +2320,14 @@ fn quote_loggable_hpp_and_cpp(
 
     (hpp, cpp)
 }
+
+fn quote_deprecation_notice(obj: &Object) -> TokenStream {
+    if let Some(deprecation_notice) = obj.deprecation_notice() {
+        // https://en.cppreference.com/w/cpp/language/attributes/deprecated
+        quote! {
+            [[deprecated(#deprecation_notice)]]
+        }
+    } else {
+        quote! {}
+    }
+}

crates/re_types_builder/src/codegen/docs/mod.rs

@@ -144,8 +144,24 @@ fn object_page(reporter: &Reporter, object: &Object, object_map: &ObjectMap) ->
 
     let mut page = String::new();
 
-    write_frontmatter(&mut page, &object.name, None);
+    let title = if object.deprecation_notice().is_some() {
+        format!("{} (deprecated)", object.name)
+    } else {
+        object.name.clone()
+    };
+
+    write_frontmatter(&mut page, &title, None);
     putln!(page);
+
+    if let Some(deprecation_notice) = object.deprecation_notice() {
+        putln!(
+            page,
+            "**⚠️ This type is deprecated and may be removed in future versions**"
+        );
+        putln!(page, "{deprecation_notice}");
+        putln!(page);
+    }
+
     for line in top_level_docs {
         putln!(page, "{line}");
     }

crates/re_types_builder/src/codegen/python.rs

@@ -362,6 +362,7 @@ impl PythonCodeGenerator {
 
             from typing import (Any, Dict, Iterable, Optional, Sequence, Set, Tuple, Union,
                 TYPE_CHECKING, SupportsFloat, Literal)
+            from typing_extensions import deprecated # type: ignore[misc, unused-ignore]
 
             from attrs import define, field
             import numpy as np
@@ -593,6 +594,10 @@ fn code_for_struct(
         ));
     }
 
+    if let Some(deprecation_notice) = obj.deprecation_notice() {
+        code.push_unindented_text(format!(r#"@deprecated("""{deprecation_notice}""")"#), 1);
+    }
+
     if !obj.is_delegating_component() {
         let define_args = if *kind == ObjectKind::Archetype {
             "str=False, repr=False, init=False"
@@ -789,6 +794,10 @@ fn code_for_union(
         format!("({})", superclasses.join(","))
     };
 
+    if let Some(deprecation_notice) = obj.deprecation_notice() {
+        code.push_unindented_text(format!(r#"@deprecated("""{deprecation_notice}""")"#), 1);
+    }
+
     code.push_unindented_text(
         format!(
             r#"

crates/re_types_builder/src/codegen/rust/api.rs

@@ -171,6 +171,9 @@ fn generate_object_file(
     code.push_str("#![allow(clippy::too_many_arguments)]\n");
     code.push_str("#![allow(clippy::too_many_lines)]\n");
     code.push_str("#![allow(clippy::unnecessary_cast)]\n");
+    if obj.deprecation_notice().is_some() {
+        code.push_str("#![allow(deprecated)]\n");
+    }
 
     code.push_str("\n\n");
 
@@ -244,6 +247,10 @@ fn generate_mod_file(
     for obj in objects {
         let module_name = obj.snake_case_name();
         let type_name = &obj.name;
+
+        if obj.deprecation_notice().is_some() {
+            code.push_str("#[allow(deprecated)]\n");
+        }
         code.push_str(&format!("pub use self::{module_name}::{type_name};\n"));
     }
 
@@ -353,6 +360,12 @@ fn quote_struct(
         .iter()
         .map(|obj_field| ObjectFieldTokenizer(reporter, obj, obj_field));
 
+    let quoted_deprecation_notice = if let Some(deprecation_notice) = obj.deprecation_notice() {
+        quote!(#[deprecated(note = #deprecation_notice)])
+    } else {
+        quote!()
+    };
+
     let is_tuple_struct = is_tuple_struct_from_obj(obj);
     let quoted_struct = if is_tuple_struct {
         quote! { pub struct #name(#(#quoted_fields,)*); }
@@ -413,6 +426,7 @@ fn quote_struct(
         #quoted_derive_clause
         #quoted_repr_clause
         #quoted_custom_clause
+        #quoted_deprecation_notice
         #quoted_struct
 
         #quoted_heap_size_bytes

crates/re_types_builder/src/lib.rs

@@ -171,6 +171,7 @@ pub const ATTR_RERUN_COMPONENT_RECOMMENDED: &str = "attr.rerun.component_recomme
 pub const ATTR_RERUN_COMPONENT_REQUIRED: &str = "attr.rerun.component_required";
 pub const ATTR_RERUN_OVERRIDE_TYPE: &str = "attr.rerun.override_type";
 pub const ATTR_RERUN_SCOPE: &str = "attr.rerun.scope";
+pub const ATTR_RERUN_DEPRECATED: &str = "attr.rerun.deprecated";
 
 pub const ATTR_PYTHON_ALIASES: &str = "attr.python.aliases";
 pub const ATTR_PYTHON_ARRAY_ALIASES: &str = "attr.python.array_aliases";

crates/re_types_builder/src/objects.rs

@@ -671,6 +671,10 @@ impl Object {
         self.try_get_attr::<String>(crate::ATTR_RERUN_SCOPE)
     }
 
+    pub fn deprecation_notice(&self) -> Option<String> {
+        self.try_get_attr::<String>(crate::ATTR_RERUN_DEPRECATED)
+    }
+
     /// Returns the crate name of an object, accounting for overrides.
     pub fn crate_name(&self) -> String {
         self.try_get_attr::<String>(crate::ATTR_RUST_OVERRIDE_CRATE)