more comments

Author: adriangb

datafusion/physical-expr-common/src/physical_expr.rs

@@ -316,6 +316,10 @@ pub trait PhysicalExpr: Send + Sync + Display + Debug + DynEq + DynHash {
     /// or needs to serialize this state to bytes may not be able to handle these dynamic references.
     /// In such cases, we should return a simplified version of the `PhysicalExpr` that does not
     /// contain these dynamic references.
+    /// 
+    /// Systems that implement remote execution of plans, e.g. serialize a portion of the query plan
+    /// and send it across the wire to a remote executor may want to call this method after
+    /// every batch on the source side and brodcast / update the current snaphot to the remote executor.
     ///
     /// Note for implementers: this method should *not* handle recursion.
     /// Recursion is handled in [`snapshot_physical_expr`].

datafusion/physical-expr/src/expressions/dynamic_filters.rs

@@ -36,7 +36,13 @@ use datafusion_physical_expr_common::physical_expr::{DynEq, DynHash};
 /// During query execution, operators implementing this trait can provide
 /// filter expressions that other operators can use to dynamically prune data.
 ///
-/// See `TopKDynamicFilterSource` in datafusion/physical-plan/src/topk/mod.rs for examples.
+/// For example:
+/// - A `HashJoin` operator can use this to provide a filter expression
+///   that filters out rows from the right side of the join based on the
+///   values from the left side.
+/// - A `TopK` operator can use this to provide a filter expression
+///   that filters out rows from the input based on the values from the
+///   top K rows.
 pub trait DynamicFilterSource:
     Send + Sync + std::fmt::Debug + DynEq + DynHash + Display + 'static
 {