docs: clarify ExecutionProps and TaskContext docs

datafusion/execution/src/task.rs

@@ -31,7 +31,23 @@ use std::{collections::HashMap, sync::Arc};
 /// execution. Please see the documentation on [`SessionContext`] for more
 /// information.
 ///
+/// # Relationship with [`ExecutionProps`]
+///
+/// [`TaskContext`] is intentionally distinct from [`ExecutionProps`].
+/// [`ExecutionProps`] is state used while optimizing a logical
+/// plan and constructing a physical plan.
+///
+/// [`TaskContext`] is the runtime context passed to physical operators when
+/// executing a physical plan. It carries runtime services and session state
+/// needed at that stage, such as [`RuntimeEnv`], memory-pool access, session
+/// configuration, and function lookup.
+///
+/// Keeping these structures separate avoids threading execution/runtime state
+/// through planning APIs, and avoids making execution depend on planner-only
+/// scratch state.
+///
 /// [`SessionContext`]: https://docs.rs/datafusion/latest/datafusion/execution/context/struct.SessionContext.html
+/// [`ExecutionProps`]: datafusion_expr::execution_props::ExecutionProps
 #[derive(Debug)]
 pub struct TaskContext {
     /// Session Id

datafusion/expr/src/execution_props.rs

@@ -22,15 +22,32 @@ use datafusion_common::alias::AliasGenerator;
 use datafusion_common::config::ConfigOptions;
 use std::sync::Arc;
 
-/// Holds per-query execution properties and data (such as statement
-/// starting timestamps).
+/// Holds properties and scratch state used while optimizing a [`LogicalPlan`]
+/// and translating it into an executable physical plan, such as the statement
+/// start time used during simplification.
 ///
 /// An [`ExecutionProps`] is created each time a `LogicalPlan` is
 /// prepared for execution (optimized). If the same plan is optimized
 /// multiple times, a new `ExecutionProps` is created each time.
 ///
 /// It is important that this structure be cheap to create as it is
 /// done so during predicate pruning and expression simplification
+///
+/// # Relationship with [`TaskContext`]
+///
+/// [`ExecutionProps`] is intentionally distinct from [`TaskContext`].
+/// It is used while optimizing a logical plan and constructing physical
+/// expressions and physical plans, before physical operators are run.
+///
+/// [`TaskContext`] is the runtime context passed to physical operators during
+/// physical-plan execution.
+///
+/// Keeping these structures separate avoids threading execution/runtime state
+/// through planning APIs, and avoids making execution depend on planner-only
+/// scratch state.
+///
+/// [`TaskContext`]: https://docs.rs/datafusion/latest/datafusion/execution/struct.TaskContext.html
+/// [`LogicalPlan`]: crate::LogicalPlan
 #[derive(Clone, Debug)]
 pub struct ExecutionProps {
     /// The time at which the query execution started. If `None`,