docs: Add module documentation to query_planner submodules (#54)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: genezhang

src/query_planner/logical_expr/errors.rs

@@ -1,3 +1,8 @@
+//! Error types for logical expression conversion.
+//!
+//! These errors occur when Cypher expressions cannot be translated
+//! to the internal LogicalExpr representation.
+
 use thiserror::Error;
 
 #[derive(Debug, Error)]

src/query_planner/logical_plan/errors.rs

@@ -1,5 +1,14 @@
+//! Error types for logical plan construction.
+//!
+//! These errors arise during the translation of Cypher AST to LogicalPlan,
+//! covering schema validation, pattern matching, and type inference issues.
+
 use thiserror::Error;
 
+/// Errors that can occur during logical plan construction.
+///
+/// These errors are typically unrecoverable and indicate problems with
+/// the query structure or schema configuration that prevent plan building.
 #[derive(Debug, Clone, Error, PartialEq)]
 pub enum LogicalPlanError {
     #[error(

src/query_planner/logical_plan/filter_view.rs

@@ -1,3 +1,8 @@
+//! Filter-ViewScan integration utilities.
+//!
+//! Provides helper methods for [`Filter`] nodes that operate on [`ViewScan`] inputs,
+//! enabling predicate pushdown and filter composition optimizations.
+
 use std::sync::Arc;
 
 use super::{Filter, LogicalPlan, ViewScan};

src/query_planner/logical_plan/match_clause/errors.rs

@@ -1,7 +1,8 @@
 //! Error types for MATCH clause processing.
 //!
-//! This module re-exports the main LogicalPlanError since match clause
-//! errors are part of the broader logical plan error hierarchy.
-
-pub use crate::query_planner::logical_plan::errors::LogicalPlanError;
-pub use crate::query_planner::logical_plan::plan_builder::LogicalPlanResult;
+//! This module serves as a placeholder for MATCH clause specific error types.
+//! Currently, match clause errors use the broader LogicalPlanError hierarchy
+//! directly via `crate::query_planner::logical_plan::errors::LogicalPlanError`.
+//!
+//! This module exists for future extensibility if match-clause-specific
+//! error variants are needed.

src/query_planner/logical_plan/mod.rs

@@ -1,3 +1,67 @@
+//! Logical Plan representation for Cypher queries.
+//!
+//! This module defines the core data structures representing a Cypher query
+//! as an intermediate representation (IR) between parsed AST and generated SQL.
+//!
+//! # Architecture Overview
+//!
+//! ```text
+//! Cypher Query → AST → LogicalPlan → SQL Query
+//!                       ^^^^^^^^^^^
+//!                       This module
+//! ```
+//!
+//! # Key Components
+//!
+//! ## Core Types
+//! - [`LogicalPlan`] - Main enum representing all query plan nodes
+//! - [`ViewScan`] - Table scan with optional predicate pushdown
+//! - [`GraphNode`] / [`GraphRel`] - Graph pattern nodes and relationships
+//! - [`Projection`] - SELECT clause items
+//! - [`Filter`] - WHERE clause conditions
+//! - [`GroupBy`] - Aggregation and grouping
+//! - [`Cte`] - Common Table Expression (WITH clause in SQL sense)
+//! - [`CartesianProduct`] - CROSS JOIN for disconnected patterns
+//! - [`Union`] - UNION/UNION ALL for combined result sets
+//!
+//! ## Clause Processing Submodules
+//! - `match_clause` - MATCH pattern to scan/join translation
+//! - `optional_match_clause` - OPTIONAL MATCH (LEFT JOIN) handling
+//! - `with_clause` - WITH clause scope/projection boundaries
+//! - `return_clause` - RETURN projection handling
+//! - `where_clause` - WHERE condition processing
+//! - `order_by_clause` - ORDER BY generation
+//! - `skip_n_limit_clause` - SKIP/LIMIT pagination
+//! - `unwind_clause` - UNWIND array expansion
+//!
+//! # Plan Building
+//!
+//! Plans are built via [`plan_builder::build_logical_plan`] which:
+//! 1. Processes Cypher clauses in order
+//! 2. Builds nodes from inner to outer (scans → joins → filters → projections)
+//! 3. Tracks planning context via [`PlanCtx`]
+//!
+//! # Example Plan Structure
+//!
+//! ```text
+//! MATCH (u:User)-[f:FOLLOWS]->(friend)
+//! WHERE u.active = true
+//! RETURN friend.name
+//!
+//! → Projection(friend.name)
+//!     └─ Filter(u.active = true)
+//!         └─ GraphRel(f:FOLLOWS)
+//!             ├─ left: ViewScan(users AS u)
+//!             ├─ center: ViewScan(follows AS f)
+//!             └─ right: ViewScan(users AS friend)
+//! ```
+//!
+//! # ID Generation
+//!
+//! For anonymous patterns, unique IDs are generated via:
+//! - [`generate_id`] - Simple incrementing aliases (t1, t2, t3...)
+//! - [`generate_cte_id`] - CTE names (cte1, cte2, cte3...)
+
 use serde::{Deserialize, Serialize};
 use std::sync::atomic::{AtomicU32, Ordering};
 use std::{collections::HashMap, fmt, sync::Arc};

src/query_planner/logical_plan/optional_match_clause.rs

@@ -1,3 +1,23 @@
+//! OPTIONAL MATCH clause processing.
+//!
+//! Handles Cypher's OPTIONAL MATCH which provides LEFT JOIN semantics -
+//! all rows from the base pattern are preserved, with NULL values
+//! where optional patterns don't match.
+//!
+//! # SQL Translation
+//!
+//! ```text
+//! MATCH (a) OPTIONAL MATCH (a)-[:FOLLOWS]->(b)
+//! → SELECT ... FROM a LEFT JOIN follows ON ... LEFT JOIN b ON ...
+//! ```
+//!
+//! # Implementation
+//!
+//! 1. Sets optional mode flag in [`PlanCtx`]
+//! 2. Processes patterns via standard MATCH logic
+//! 3. Aliases are auto-marked as optional for JOIN generation
+//! 4. Restores normal mode after processing
+
 use std::sync::Arc;
 
 use crate::{

src/query_planner/logical_plan/order_by_clause.rs

@@ -1,3 +1,15 @@
+//! ORDER BY clause processing.
+//!
+//! Converts Cypher ORDER BY clauses into [`OrderBy`] logical plan nodes.
+//! Supports ascending/descending sort direction and multiple sort keys.
+//!
+//! # SQL Translation
+//!
+//! ```text
+//! ORDER BY u.name DESC, u.age ASC
+//! → ORDER BY users.full_name DESC, users.age ASC
+//! ```
+
 use std::sync::Arc;
 
 use crate::{

src/query_planner/logical_plan/plan_builder.rs

@@ -1,3 +1,33 @@
+//! Logical plan builder for Cypher queries.
+//!
+//! This module orchestrates the construction of [`LogicalPlan`] trees from
+//! parsed Cypher AST. It processes clauses in sequential order, building
+//! up the plan from innermost scans to outermost projections.
+//!
+//! # Clause Processing Order
+//!
+//! ```text
+//! 1. MATCH clauses      → ViewScan, GraphNode, GraphRel nodes
+//! 2. OPTIONAL MATCH     → CartesianProduct with is_optional=true
+//! 3. UNWIND clauses     → Unwind nodes (ARRAY JOIN)
+//! 4. WHERE clause       → Filter nodes
+//! 5. WITH clause        → WithClause (scope boundary + projection)
+//! 6. ORDER BY           → OrderBy nodes
+//! 7. SKIP/LIMIT         → Skip/Limit nodes
+//! 8. RETURN clause      → Projection nodes
+//! ```
+//!
+//! # Key Functions
+//!
+//! - [`build_logical_plan`] - Main entry point for plan construction
+//!
+//! # Error Handling
+//!
+//! Returns [`LogicalPlanResult`] wrapping [`LogicalPlanError`] for:
+//! - Schema validation failures
+//! - Unsupported syntax
+//! - Type inference errors
+
 use std::collections::HashMap;
 use std::sync::Arc;
 

src/query_planner/logical_plan/projection_view.rs

@@ -1,3 +1,8 @@
+//! Projection-ViewScan integration utilities.
+//!
+//! Provides helper methods for [`Projection`] nodes that operate on [`ViewScan`] inputs,
+//! enabling column mapping and projection pushdown optimizations.
+
 use std::sync::Arc;
 
 use super::{LogicalPlan, Projection, ProjectionItem, ViewScan};

src/query_planner/logical_plan/return_clause.rs

@@ -1,3 +1,21 @@
+//! RETURN clause processing.
+//!
+//! Handles Cypher's RETURN clause which projects and optionally aggregates results.
+//! Creates [`Projection`] and [`GroupBy`] logical plan nodes.
+//!
+//! # Features
+//!
+//! - Simple projections: `RETURN u.name, u.email`
+//! - Aggregations: `RETURN count(*), avg(score)`
+//! - Aliasing: `RETURN u.name AS userName`
+//! - DISTINCT: `RETURN DISTINCT u.country`
+//! - Whole-entity: `RETURN u` (returns all properties as JSON)
+//!
+//! # Aggregation Handling
+//!
+//! When aggregates are detected, non-aggregate columns are automatically
+//! added to GROUP BY (ClickHouse requires explicit grouping).
+
 use crate::{
     open_cypher_parser::ast::{Expression, ReturnClause, ReturnItem},
     query_planner::logical_expr::{