documentation improvements

crates/re_space_view_spatial/src/scene/contexts/depth_offsets.rs

@@ -5,10 +5,12 @@ use re_components::DrawOrder;
 use re_log_types::{Component, EntityPathHash};
 use re_viewer_context::{ArchetypeDefinition, SceneContextPart};
 
-// TODO(wumpf): In the new traitified system it would be likely more ergonomic to map from darw order to depth offset
-//              This would also yield more consistent/meaningful archetypes and avoid queries where not needed.
+/// Context for creating a mapping from [`DrawOrder`] to [`re_renderer::DepthOffset`].
 #[derive(Default)]
 pub struct EntityDepthOffsets {
+    // TODO(wumpf): Given that archetypes (should) contain DrawData, we should have a map of DrawData to DepthOffset.
+    //              Mapping entities to depth offset instead is inconsistent with the archetype queries which are
+    //              expected to care about DepthOffset iff they can make use of it.
     pub per_entity: IntMap<EntityPathHash, re_renderer::DepthOffset>,
     pub box2d: re_renderer::DepthOffset,
     pub lines2d: re_renderer::DepthOffset,

crates/re_space_view_spatial/src/scene/parts/entity_iterator.rs

@@ -5,6 +5,10 @@ use re_viewer_context::{ArchetypeDefinition, SceneQuery, SpaceViewHighlights, Vi
 
 use crate::scene::contexts::{SpatialSceneContext, SpatialSceneEntityContext};
 
+/// Iterates through all entity views for a given archetype.
+///
+/// The callback passed in gets passed a long an [`SpatialSceneEntityContext`] which contains
+/// various useful information about an entity in the context of the current scene.
 pub fn process_entity_views<'a, Primary, const N: usize, F>(
     ctx: &mut ViewerContext<'_>,
     query: &SceneQuery<'_>,

crates/re_space_view_spatial/src/scene/parts/spatial_scene_part_data.rs

@@ -1,6 +1,8 @@
 use crate::scene::UiLabel;
 
 /// Common data struct for all spatial scene elements.
+///
+/// Each spatial scene element is expected to fill an instance of this struct with its data.
 pub struct SpatialScenePartData {
     pub ui_labels: Vec<UiLabel>,
     pub bounding_box: macaw::BoundingBox,

crates/re_viewer_context/src/space_view/scene.rs

@@ -7,6 +7,9 @@ use crate::{
 ///
 /// When populating a scene, first all contexts are populated,
 /// and then all elements with read access to the previously established context objects.
+///
+/// In practice, the only thing implementing [`Scene`] is [`TypedScene`] which in turn is defined by
+/// by a concrete [`SpaceViewClassImpl`].
 pub trait Scene {
     /// Populates the scene for a given query.
     fn populate(

crates/re_viewer_context/src/space_view/scene_part.rs

@@ -36,8 +36,9 @@ pub trait ScenePart<C: SpaceViewClassImpl> {
 
     /// Optionally retrieves a data store reference from the scene element.
     ///
-    /// This is a useful for retrieving a data struct that may be common for all scene elements
-    /// of a particular [`crate::SpaceViewClass`].
+    /// This is useful for retrieving data that is common to all scene parts of a [`crate::SpaceViewClass`].
+    /// For example, if most scene parts produce ui elements, a concrete [`crate::SpaceViewClassImpl`]
+    /// can pick those up in its [`crate::SpaceViewClassImpl::ui`] method by iterating over all scene parts.
     fn data(&self) -> Option<&C::ScenePartData> {
         None
     }

crates/re_viewer_context/src/space_view/space_view_class.rs

@@ -77,7 +77,11 @@ pub trait SpaceViewClass {
     );
 }
 
-/// State of a space view.
+/// Unserialized frame to frame state of a space view.
+///
+/// For any state that should be persisted, use the Blueprint!
+/// This state is used for transient state, such as animation or uncommited ui state like dragging a camera.
+/// (on mouse release, the camera would be commited to the blueprint).
 pub trait SpaceViewState: std::any::Any {
     /// Converts itself to a reference of [`std::any::Any`], which enables downcasting to concrete types.
     fn as_any(&self) -> &dyn std::any::Any;

crates/re_viewer_context/src/space_view/space_view_class_impl.rs

@@ -21,6 +21,10 @@ pub trait SpaceViewClassImpl: std::marker::Sized {
     type ScenePartCollection: ScenePartCollection<Self> + Default + 'static;
 
     /// A piece of data that all scene parts have in common, useful for iterating over them.
+    ///
+    /// This is useful for retrieving data that is common to all scene parts of a [`SpaceViewClass`].
+    /// For example, if most scene parts produce ui elements, a concrete [`SpaceViewClassImpl`]
+    /// can pick those up in its [`SpaceViewClassImpl::ui`] method by iterating over all scene parts.
     type ScenePartData;
 
     /// Name of this space view class.