add docs for everything

optd-core/src/expression/mod.rs

@@ -1,9 +1,13 @@
-pub mod relational;
-pub mod scalar;
+//! Type definitons that compose the [`Expr`] expression type, which represents all relational and
+//! scalar expressions contained in the memo table that are used for dynamic programming during
+//! query optimization.
 
 /// A type representing an optimization operator in the memo table.
 #[derive(Clone)]
 pub enum Expr {
     Relational(relational::RelationalExpr),
     Scalar(scalar::ScalarExpr),
 }
+
+pub mod relational;
+pub mod scalar;

optd-core/src/expression/relational.rs

@@ -1,12 +1,31 @@
+//! Type definitions that compose relational expressions, which can be either logical or physical.
+//!
+//! Note that both [`LogicalExpr`] and [`PhysicalExpr`] are defined over the [`LogicalOperator`] and
+//! [`PhysicalOperator`] for the purpose of code reuse. See the type documentation for more detailed
+//! information.
+
 use crate::{
     operator::relational::{logical::LogicalOperator, physical::PhysicalOperator},
-    GroupId,
+    GroupId, ScalarGroupId,
 };
 
-pub type LogicalExpr = LogicalOperator<GroupId, GroupId>;
-pub type PhysicalExpr = PhysicalOperator<GroupId, GroupId>;
+/// A representation of a logical expression, which is used as the in-memory representation of
+/// logical expressions in the memo table.
+///
+/// Note that this type is defined over the [`LogicalOperator`] type, as the only semantic
+/// difference between operators and expressions is that operators have pointers to other operators
+/// as children, whereas expressions have [`GroupId`]s as children.
+pub type LogicalExpr = LogicalOperator<GroupId, ScalarGroupId>;
+
+/// A representation of a physical expression, which is used as the in-memory representation of
+/// physical expressions in the memo table.
+///
+/// Note that this type is defined over the [`PhysicalOperator`] type, as the only semantic
+/// difference between operators and expressions is that operators have pointers to other operators
+/// as children, whereas expressions have [`GroupId`]s as children.
+pub type PhysicalExpr = PhysicalOperator<GroupId, ScalarGroupId>;
 
-/// A type representing logical or physical expressions in the memo table.
+/// A type representing logical or physical expressions from the memo table.
 #[derive(Clone)]
 pub enum RelationalExpr {
     Logical(LogicalExpr),

optd-core/src/expression/scalar.rs

@@ -1,3 +1,5 @@
+//! TODO FIGURE EVERYTHING OUT HERE.
+
 /// A type that represent scalar SQL expression / predicates.
 ///
 /// TODO Add fields to this type.

optd-core/src/lib.rs

@@ -6,11 +6,16 @@ pub mod operator;
 pub mod plan;
 pub mod rules;
 
-/// TODO make distinction between relational groups and scalar groups.
+/// A unique identifier for a relational group of expressions.
 #[repr(transparent)]
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct GroupId(u64);
 
+/// A unique identifier for a scalar group of scalar trees / expressions / operations.
+#[repr(transparent)]
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct ScalarGroupId(u64);
+
 /// TODO Add docs.
 #[allow(dead_code)]
 pub struct ExprId(u64);

optd-core/src/memo.rs

@@ -1,8 +1,10 @@
 use crate::expression::Expr;
 use crate::{ExprId, GroupId};
 
+/// TODO Add fields.
 pub struct Memo;
 
+/// TODO Stabilize API.
 impl Memo {
     pub async fn add_expr(&mut self, logical_expr: Expr) -> (ExprId, GroupId) {
         todo!()

optd-core/src/operator/mod.rs

@@ -1,5 +1,5 @@
 //! This module contains items related to query plan operators, both relational (logical / physical)
-//! and scalar.
+//! and scalar operator trees.
 
 pub mod relational;
 pub mod scalar;

optd-core/src/operator/relational/logical/filter.rs

@@ -1,3 +1,5 @@
+/// A logical filter operation.
+///
 /// TODO Add docs.
 #[derive(Clone)]
 pub struct LogicalFilter<Child, Scalar> {

optd-core/src/operator/relational/logical/join.rs

@@ -1,3 +1,5 @@
+/// A logical join operation.
+///
 /// TODO Add docs.
 #[derive(Clone)]
 pub struct LogicalJoin<Child, Scalar> {

optd-core/src/operator/relational/logical/mod.rs

@@ -9,8 +9,8 @@
 /// allowed to have in whatever kind of plan it is contained in. This makes it possible to reuse the
 /// `LogicalOperator` type in differnt kinds of trees.
 ///
-/// For example, `LogicalOperator` is a valid operator in [`LogicalPlan`], [`PhysicalPlan`], and
-/// [`PartialLogicalPlan`].
+/// This type is also generic over a `Scalar` type, which specifies what type of scalar / predicate
+/// types this operator can contain.
 ///
 /// [`LogicalPlan`]: crate::plan::logical_plan::LogicalPlan
 /// [`PhysicalPlan`]: crate::plan::physical_plan::PhysicalPlan

optd-core/src/operator/relational/logical/scan.rs

@@ -1,3 +1,5 @@
+/// A logical scan operation.
+///
 /// TODO Add docs.
 #[derive(Clone)]
 pub struct LogicalScan<Scalar> {

optd-core/src/operator/relational/mod.rs

@@ -1,2 +1,4 @@
+//! Types and definitions for relational (logical and physical) operators.
+
 pub mod logical;
 pub mod physical;

optd-core/src/operator/relational/physical/filter.rs

@@ -1,3 +1,5 @@
+/// A physical filter operation.
+///
 /// TODO Add docs.
 #[derive(Clone)]
 pub struct PhysicalFilter<Child, Scalar> {

optd-core/src/operator/relational/physical/hash_join.rs

@@ -1,3 +1,5 @@
+/// A physical hash join operation.
+///
 /// TODO Add docs.
 #[derive(Clone)]
 pub struct HashJoin<Child, Scalar> {

optd-core/src/operator/relational/physical/mod.rs

@@ -9,8 +9,8 @@
 /// allowed to have in whatever kind of plan it is contained in. This makes it possible to reuse the
 /// `PhysicalOperator` type in differnt kinds of trees.
 ///
-/// For example, `PhysicalOperator` _**is**_ a valid operator in [`PhysicalPlan`], _**but it is not
-/// a valid operator in**_ [`LogicalPlan`] nor [`PartialLogicalPlan`].
+/// This type is also generic over a `Scalar` type, which specifies what type of scalar / predicate
+/// types this operator can contain.
 ///
 /// [`LogicalPlan`]: crate::plan::logical_plan::LogicalPlan
 /// [`PhysicalPlan`]: crate::plan::physical_plan::PhysicalPlan

optd-core/src/operator/relational/physical/table_scan.rs

@@ -1,3 +1,5 @@
+/// A physical table scan operation.
+///
 /// TODO Add docs.
 #[derive(Clone)]
 pub struct TableScan<Scalar> {

optd-core/src/operator/scalar.rs

@@ -1,3 +1,5 @@
+//! TODO FIGURE EVERYTHING OUT HERE.
+
 /// TODO Add fields.
 #[derive(Clone)]
 pub struct ScalarOperator {}

optd-core/src/plan/logical_plan.rs

@@ -1,16 +1,17 @@
+//! This module contains the [`LogicalPlan`] type, which is the representation of a logical query
+//! plan from SQL.
+
 use crate::operator::{relational::logical::LogicalOperator, scalar::ScalarOperator};
 use std::sync::Arc;
 
 /// A representation of a logical query plan DAG (directed acyclic graph).
 ///
-/// The `LogicalPlan` DAG consists of [`LogicalOperator<LogicalLink>`] and
-/// `ScalarOperator<ScalarLink>` nodes, where the generic links denote the kinds of children each of
-/// those operators are allowed to have. For example, logical operators are allowed to have both
-/// logical and scalar operators as children, but scalar operators are only allowed to have other
-/// scalar operators as children.
+/// A logical plan consists of only logical operators and scalars.
 ///
 /// The root of the plan DAG _cannot_ be a scalar operator (and thus for now can only be a logical
 /// operator).
+///
+/// TODO Add more docs.
 #[derive(Clone)]
 pub struct LogicalPlan {
     pub root: Arc<LogicalOperator<LogicalPlan, ScalarOperator>>,

optd-core/src/plan/mod.rs

@@ -1,3 +1,6 @@
+//! Types and definitions for representing logical and physical plans, both fully materialized and
+//! partially materialized.
+
 pub mod logical_plan;
 pub mod partial_logical_plan;
 pub mod physical_plan;

optd-core/src/plan/partial_logical_plan.rs

@@ -7,10 +7,11 @@ use std::sync::Arc;
 ///
 /// Similar to a [`LogicalPlan`], the `PartialLogicalPlan` DAG consists of both logical and scalar
 /// operator nodes, but it can also have unmaterialized [`GroupId`]s representing entire memo groups
-/// as children.
+/// as children. This behavior is defined by the [`LogicalLink`] type that is passed in as the
+/// generic child type for [`LogicalOperator`].
 ///
-/// Note that while logical nodes can have both logical and scalar nodes as children, scalar nodes can only have other scalar
-/// nodes as children.
+/// Note that while logical nodes can have both logical and scalar nodes as children, scalar nodes
+/// can only have other scalar nodes as children.
 ///
 /// Note that the root of the plan _cannot_ be a scalar operator (and thus can only be a logical
 /// operator).
@@ -23,16 +24,8 @@ pub struct PartialLogicalPlan {
 
 /// A link in a [`PartialLogicalPlan`] to a node.
 ///
-/// A `LogicalLink` can be one of three things: it can be a `LogicalNode` that points to a
-/// `LogicalOperator`, it can be a `ScalarNode` that points to a `ScalarOperator`, or it can be a
+/// A `LogicalLink` can either be a `LogicalNode` that points to a `LogicalOperator`, or it can be a
 /// [`GroupId`], denoting the unamterialized part of the plan (thus the name `PartialLogicalPlan`).
-///
-/// Note that this `LogicalLink` is _**different**_ from the `LogicalLink`s defined in the sibling
-/// module [`super::logical_plan`]. [`LogicalPlan`] does not need to have [`GroupId`]s as children,
-/// and so its type representation does not allow that.
-///
-/// [`GroupId`]: crate::GroupId
-/// [`LogicalPlan`]: crate::plan::logical_plan::LogicalPlan
 #[derive(Clone)]
 pub enum LogicalLink {
     LogicalNode(Arc<LogicalOperator<LogicalLink, ScalarOperator>>),

optd-core/src/plan/physical_plan.rs

@@ -1,7 +1,17 @@
+//! This module contains the [`PhysicalPlan`] type, which is the representation of a physical
+//! execution plan that will be sent to an query execution engine.
+
 use crate::operator::{relational::physical::PhysicalOperator, scalar::ScalarOperator};
 use std::sync::Arc;
 
-/// TODO Add docs.
+/// A representation of a physical query plan DAG (directed acyclic graph).
+///
+/// A physical plan consists of only physical operators and scalars.
+///
+/// The root of the plan DAG _cannot_ be a scalar operator (and thus for now can only be a physical
+/// operator).
+///
+/// TODO Add more docs.
 #[derive(Clone)]
 pub struct PhysicalPlan {
     pub root: Arc<PhysicalOperator<PhysicalPlan, ScalarOperator>>,

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

@@ -1,3 +1,8 @@
+//! This module contains the implementation rule trait / API, as well as the rules that implement
+//! said trait.
+//!
+//! TODO Add more docs.
+
 use crate::expression::relational::{LogicalExpr, PhysicalExpr};
 
 #[allow(dead_code)]

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

@@ -1,3 +1,8 @@
+//! This module contains the transformation rule trait / API, as well as the rules that implement
+//! said trait.
+//!
+//! TODO Add more docs.
+
 use crate::{
     expression::{relational::LogicalExpr, Expr},
     memo::Memo,