format and add docs for the plan module

docs/src/architecture/glossary.md

@@ -126,7 +126,7 @@ See the following sections for more information.
 
 A logical expression is a version of a [Relational Expression].
 
-TODO(connor) Add more details.
+TODO(connor): Add more details.
 
 Examples of logical expressions include Logical Scan, Logical Join, or Logical Sort expressions
 (which can just be shorthanded to Scan, Join, or Sort).
@@ -135,7 +135,7 @@ Examples of logical expressions include Logical Scan, Logical Join, or Logical S
 
 A physical expression is a version of a [Relational Expression].
 
-TODO(connor) Add more details.
+TODO(connor): Add more details.
 
 Examples of physical expressions include Table Scan, Index Scan, Hash Join, or Sort Merge Join.
 

optd-core/src/plan/logical_plan.rs

@@ -1,5 +1,7 @@
 //! This module contains the [`LogicalPlan`] type, which is the representation of a logical query
 //! plan from SQL.
+//!
+//! See the documentation for [`LogicalPlan`] for more information.
 
 use super::scalar_plan::ScalarPlan;
 use crate::operator::relational::logical::LogicalOperator;
@@ -15,5 +17,9 @@ use std::sync::Arc;
 /// TODO(connor): add more docs.
 #[derive(Clone)]
 pub struct LogicalPlan {
+    /// Represents the current logical operator that is the root of the current subplan.
+    ///
+    /// Note that the children of the operator are other plans, which means that this data structure
+    /// is an in-memory DAG (directed acyclic graph) of logical operators.
     pub node: Arc<LogicalOperator<LogicalPlan, ScalarPlan>>,
 }

optd-core/src/plan/partial_logical_plan.rs

@@ -1,11 +1,17 @@
-use crate::memo::GroupId;
+//! This module contains the [`PartialLogicalPlan`] type, which is the representation of a partially
+//! materialized logical query plan that is a mix of materialized logical operators and
+//! unmaterialized group ID references to memo table groups of expressions.
+//!
+//! See the documentation for [`PartialLogicalPlan`] for more information.
+
+use crate::memo::{GroupId, ScalarGroupId};
 use crate::operator::relational::logical::LogicalOperator;
 use crate::operator::scalar::ScalarOperator;
 use std::sync::Arc;
 
 /// A partially materialized logical query plan represented as a DAG (directed acyclic graph).
 ///
-/// While a [`LogicalPlan`] contains fully materialized operator nodes, a `PartialLogicalPlan`
+/// While a [`LogicalPlan`] contains fully materialized operator nodes, a [`PartialLogicalPlan`]
 /// can contain both materialized nodes and references to unmaterialized memo groups. This enables
 /// efficient plan exploration and transformation during query optimization.
 ///
@@ -24,27 +30,38 @@ use std::sync::Arc;
 /// [`LogicalPlan`]: crate::plan::logical_plan::LogicalPlan
 #[derive(Clone)]
 pub struct PartialLogicalPlan {
+    /// Represents the current logical operator that is the root of the current partially
+    /// materialized subplan.
+    ///
+    /// Note that the children of the operator are either a [`Relation`] or a [`Scalar`], both of
+    /// which are defined in this module. See their documentation for more information.
     pub node: Arc<LogicalOperator<Relation, Scalar>>,
 }
 
 /// A link to a relational node in a [`PartialLogicalPlan`].
 ///
-/// Can be either:
-/// - A materialized logical operator node
-/// - A reference to an unmaterialized memo group
+/// This link (which denotes what kind of relational children the operators of a
+/// [`PartialLogicalPlan`] can have) can be either:
+/// - A materialized logical operator node.
+/// - A reference (identifier) to an unmaterialized memo group.
 #[derive(Clone)]
 pub enum Relation {
+    /// A materialized logical operator node.
     Operator(Arc<LogicalOperator<Relation, Scalar>>),
+    /// A reference (identifier) to an unmaterialized memo group.
     GroupId(GroupId),
 }
 
 /// A link to a scalar node in a [`PartialLogicalPlan`].
 ///
-/// Can be either:
-/// - A materialized scalar operator node
-/// - A reference to an unmaterialized memo group
+/// This link (which denotes what kind of scalar children the operators of a [`PartialLogicalPlan`]
+/// can have) can be either:
+/// - A materialized scalar operator node.
+/// - A reference to an unmaterialized memo group.
 #[derive(Clone)]
 pub enum Scalar {
+    /// A materialized scalar operator node.
     Operator(Arc<ScalarOperator<Scalar>>),
-    GroupId(GroupId),
+    /// A reference to an unmaterialized memo group.
+    ScalarGroupId(ScalarGroupId),
 }

optd-core/src/plan/physical_plan.rs

@@ -1,5 +1,7 @@
 //! This module contains the [`PhysicalPlan`] type, which is the representation of a physical
 //! execution plan that can be sent to a query execution engine.
+//!
+//! See the documentation for [`PhysicalPlan`] for more information.
 
 use super::scalar_plan::ScalarPlan;
 use crate::operator::relational::physical::PhysicalOperator;
@@ -15,5 +17,9 @@ use std::sync::Arc;
 /// TODO(connor): add more docs.
 #[derive(Clone)]
 pub struct PhysicalPlan {
+    /// Represents the current physical operator that is the root of the current subplan.
+    ///
+    /// Note that the children of the operator are other plans, which means that this data structure
+    /// is an in-memory DAG (directed acyclic graph) of physical operators.
     pub node: Arc<PhysicalOperator<PhysicalPlan, ScalarPlan>>,
 }

optd-core/src/plan/scalar_plan.rs

@@ -1,9 +1,13 @@
-use std::sync::Arc;
+//! TODO(everyone): Figure out what exactly a `ScalarPlan` is (tree? DAG? always materialized?)
 
 use crate::operator::scalar::ScalarOperator;
+use std::sync::Arc;
 
 /// A representation of a scalar query plan DAG (directed acyclic graph).
 #[derive(Clone)]
 pub struct ScalarPlan {
+    /// Represents the current scalar operator that is the root of the current scalar subtree.
+    ///
+    /// TODO(connor): Figure out if scalar plans can be a DAG
     pub node: Arc<ScalarOperator<ScalarPlan>>,
 }

optd-core/src/rules/implementation/mod.rs

@@ -1,7 +1,7 @@
 //! This module contains the implementation rule trait / API, as well as the rules that implement
 //! said trait.
 //!
-//! TODO(connor) Add more docs.
+//! TODO(connor): Add more docs.
 
 use crate::expression::{LogicalExpression, PhysicalExpression};
 

optd-core/src/rules/implementation/physical_filter.rs

@@ -19,6 +19,9 @@ impl ImplementationRule for PhysicalFilterRule {
             return None;
         };
 
-        Some(PhysicalOperator::Filter(PhysicalFilter { child, predicate }))
+        Some(PhysicalOperator::Filter(PhysicalFilter {
+            child,
+            predicate,
+        }))
     }
 }

optd-core/src/rules/transformation/join_associativity.rs

@@ -1,11 +1,11 @@
 //! The rule for join associativity.
-//! 
+//!
 //! See [`JoinAssociativityRule`] for more information.
 
 use super::*;
 
 /// A unit / marker struct for join associativity.
-/// 
+///
 /// Since joining is an associative operation, we can convert a `Join(Join(A, B), C)` into a
 /// `Join(A, Join(B, C))`.
 pub struct JoinAssociativityRule;

optd-core/src/rules/transformation/join_commutativity.rs

@@ -1,11 +1,11 @@
 //! The rule for join commutativity.
-//! 
+//!
 //! See [`JoinCommutativityRule`] for more information.
 
 use super::*;
 
 /// A unit / marker struct for join commutativity.
-/// 
+///
 /// Since joining is an commutative operation, we can convert a `Join(A, B)` into a `Join(B, C)`.
 pub struct JoinCommutativityRule;
 

optd-core/src/rules/transformation/mod.rs

@@ -33,7 +33,7 @@ pub trait TransformationRule {
     ///
     /// These changes can create new logical or scalar expressions. However, note that
     /// transformation rules will _not_ create new physical expressions.
-    /// 
+    ///
     /// TODO(everyone) Figure out what the return type should really be.
     fn apply(&self, expr: PartialLogicalPlan) -> PartialLogicalPlan;
 }