Add comments to view system

Author: Dampfwalze

doc/technical_overview.md

@@ -44,9 +44,9 @@ The [main app](/src/app.rs#L19) consists of the [high level
 `Pipeline`](#high-level-pipeline), the [pipelines execution
 system](#execution-of-the-pipeline) and the [pipelines editing
 state](#editing-of-the-pipeline). As well as a
-[`DataViewsState`](/src/view/mod.rs#L25), a
-[`DataViewsManager`](/src/view/views_manager.rs#L62) and a
-[`ViewsExecutor`](/src/view/execution/executor.rs#L21). It also stores the
+[`DataViewsState`](/src/view/mod.rs#L32), a
+[`DataViewsManager`](/src/view/views_manager.rs#L64) and a
+[`ViewsExecutor`](/src/view/execution/executor.rs#L25). It also stores the
 global [`DockState`](/src/gui/dock_state.rs#L18) and provides a
 [`Cache`](/src/cache.rs#L14).
 

src/view/execution/executor.rs

@@ -18,6 +18,10 @@ use super::DynDataViewTask;
 
 // MARK: ViewsExecutor
 
+/// Execution system for data view tasks, described by [super::DataViewTask].
+///
+/// Analog to the pipelines execution system. Tasks in this system can connect
+/// to tasks in the pipelines execution system.
 pub struct ViewsExecutor {
     runners: HashMap<ViewId, ViewTaskRunner>,
 }

src/view/execution/mod.rs

@@ -9,6 +9,12 @@ use crate::{
 
 use super::views::{DataView, DynDataView};
 
+/// Describes a data view task.
+///
+/// A data view task connects into the pipelines execution system and is
+/// responsible for acquiring data to be rendered inside the view. Since it is
+/// run in a concurrent context, it should also handle all operations on the
+/// data that are required for rendering.
 pub trait DataViewTask: Send + Sync + 'static {
     type InputId: From<InputId> + Into<InputId>;
     type DataView: DataView;
@@ -28,6 +34,8 @@ pub trait DataViewTask: Send + Sync + 'static {
     fn run(&mut self) -> impl Future<Output = anyhow::Result<()>> + Send;
 }
 
+/// Dynamic version of [DataViewTask]. This trait is implemented automatically
+/// for all types implementing [DataViewTask] and can be used as a trait object.
 pub trait DynDataViewTask: Send + Sync {
     fn sync_view(&mut self, node: &dyn DynDataView);
 

src/view/mod.rs

@@ -22,6 +22,13 @@ impl Into<usize> for ViewId {
     }
 }
 
+/// High level description of data views and their connections into the
+/// pipeline.
+///
+/// Data views are analog to pipeline nodes, with the main difference that they
+/// render into their own tab. They are very similar to pipeline nodes, but have
+/// their own management system and execution system. They can connect into the
+/// pipeline.
 pub struct DataViewsState {
     views: HashMap<ViewId, Box<dyn DynDataView>>,
 }

src/view/views/data_vector.rs

@@ -14,6 +14,7 @@ pub struct View {
     data_rx: Option<watch::Receiver<Option<Arc<DataVector>>>>,
 }
 
+/// Renders a plot of a [DataVector].
 impl DataView for View {
     type InputId = InputIdSingle;
 

src/view/views/m_scan.rs

@@ -39,6 +39,10 @@ impl_enum_from_into_id_types!(InputId, [graph::InputId], {
 
 // MARK: View
 
+/// Renders M scans in three different perspectives.
+///
+/// Each M scan gets fully uploaded to the GPU. The different perspectives are
+/// achieved by sampling the scan data in a specific way on the GPU.
 pub struct View {
     m_scan: NodeOutput,
     b_scan_segmentation: Option<NodeOutput>,

src/view/views/mesh.rs

@@ -12,6 +12,7 @@ use super::prelude::*;
 
 // MARK: View
 
+/// Renders a [types::LumenMesh].
 #[derive(Clone, Debug)]
 pub struct View {
     mesh: NodeOutput,

src/view/views/mod.rs

@@ -45,6 +45,10 @@ pub enum Existence {
     Keep,
 }
 
+/// Describes a data view.
+///
+/// Data views are rendered in their own tab and can connect to multiple nodes
+/// in the pipeline. The implementer is responsible for rendering the view.
 pub trait DataView: Send + Sync + Clone + 'static {
     type InputId: From<InputId> + Into<InputId>;
 
@@ -80,6 +84,8 @@ pub trait DataView: Send + Sync + Clone + 'static {
     fn ui(&mut self, ui: &mut egui::Ui);
 }
 
+/// Dynamic version of [DataView]. This trait is implemented automatically for
+/// all types implementing [DataView] and can be used as a trait object.
 pub trait DynDataView: Send + Sync + 'static {
     fn as_any(&self) -> &dyn any::Any;
 

src/view/views_manager.rs

@@ -59,6 +59,8 @@ impl<'a> DataViewsManagerBuilder<'a> {
     }
 }
 
+/// Creates, removes and changes data views inside a [DataViewsState] in
+/// response to user interactions.
 pub struct DataViewsManager {
     view_factories: Vec<
         Box<dyn Fn(&NodeOutput, &Pipeline, &Cache, &RenderState) -> Option<Box<dyn DynDataView>>>,