CodeGeneratorWithInterpretedFallbacks and UnsafeProjection

Author: jaceklaskowski

docs/expressions/CodeGeneratorWithInterpretedFallback.md

@@ -1,40 +1,70 @@
-# CodeGeneratorWithInterpretedFallback Generators
+---
+title: CodeGeneratorWithInterpretedFallback
+---
 
-`CodeGeneratorWithInterpretedFallback` is an [abstraction](#contract) of [codegen object generators](#implementations) that can create objects for [codegen](#createCodeGeneratedObject) and [interpreted](#createInterpretedObject) evaluation paths.
+# CodeGeneratorWithInterpretedFallback Generators
 
-## Type Constructor
+`CodeGeneratorWithInterpretedFallback` is an [abstraction](#contract) of [codegen object generators](#implementations) that can [create `OUT` objects](#createObject) for [codegen](#createCodeGeneratedObject) and [interpreted](#createInterpretedObject) evaluation paths.
 
 `CodeGeneratorWithInterpretedFallback` is a Scala type constructor (_generic class_) with `IN` and `OUT` type aliases.
 
 ```scala
 CodeGeneratorWithInterpretedFallback[IN, OUT]
 ```
 
+CodeGeneratorWithInterpretedFallback | IN | OUT
+-------------------------------------|----|----
+ [RowOrdering](RowOrdering.md) | [SortOrder](SortOrder.md)s (`Seq[SortOrder]`) | `BaseOrdering`
+ [Predicate](Predicate.md) | [Expression](Expression.md) | `BasePredicate`
+ [MutableProjection](MutableProjection.md) | [Expression](Expression.md)s (`Seq[Expression]`) | [MutableProjection](MutableProjection.md)
+ [UnsafeProjection](UnsafeProjection.md) | [Expression](Expression.md)s (`Seq[Expression]`) | [UnsafeProjection](UnsafeProjection.md)
+ `SafeProjection` | [Expression](Expression.md)s (`Seq[Expression]`) | [Projection](Projection.md)
+
 ## Contract
 
-### <span id="createCodeGeneratedObject"> createCodeGeneratedObject
+### createCodeGeneratedObject { #createCodeGeneratedObject }
 
 ```scala
 createCodeGeneratedObject(
   in: IN): OUT
 ```
 
-### <span id="createInterpretedObject"> createInterpretedObject
+See:
+
+* [MutableProjection](MutableProjection.md#createCodeGeneratedObject)
+* [UnsafeProjection](UnsafeProjection.md#createCodeGeneratedObject)
+* [RowOrdering](RowOrdering.md#createCodeGeneratedObject)
+
+Used when:
+
+* `CodeGeneratorWithInterpretedFallback` is requested to [create an `OUT` object](#createObject)
+
+### createInterpretedObject { #createInterpretedObject }
 
 ```scala
 createInterpretedObject(
   in: IN): OUT
 ```
 
+See:
+
+* [MutableProjection](MutableProjection.md#createInterpretedObject)
+* [UnsafeProjection](UnsafeProjection.md#createInterpretedObject)
+* [RowOrdering](RowOrdering.md#createInterpretedObject)
+
+Used when:
+
+* `CodeGeneratorWithInterpretedFallback` is requested to [create an `OUT` object](#createObject) (after [createCodeGeneratedObject](#createCodeGeneratedObject) failed with a non-fatal exception)
+
 ## Implementations
 
-* `MutableProjection`
+* [MutableProjection](MutableProjection.md)
 * [Predicate](Predicate.md)
 * [RowOrdering](RowOrdering.md)
 * `SafeProjection`
 * [UnsafeProjection](UnsafeProjection.md)
 
-## <span id="createObject"> Creating Object
+## Creating OUT Object { #createObject }
 
 ```scala
 createObject(
@@ -49,10 +79,12 @@ In case of a non-fatal exception, `createObject` prints out the following WARN m
 Expr codegen error and falling back to interpreter mode
 ```
 
+---
+
 `createObject` is used when:
 
-* `MutableProjection` utility is used to create a `MutableProjection`
+* `MutableProjection` utility is used to [create a MutableProjection](MutableProjection.md#create)
 * `Predicate` utility is used to [create a BasePredicate](Predicate.md#create)
 * `RowOrdering` utility is used to [create a BaseOrdering](RowOrdering.md#create)
 * `SafeProjection` utility is used to create a `Projection`
-* `UnsafeProjection` utility is used to [create a UnsafeProjection](UnsafeProjection.md#create)
+* `UnsafeProjection` utility is used to [create an UnsafeProjection](UnsafeProjection.md#create)

docs/expressions/UnsafeProjection.md

@@ -1,14 +1,16 @@
 # UnsafeProjection
 
-`UnsafeProjection` is an [extension](#contract) of the [Projection](Projection.md) abstraction for [expressions](#implementations) that [encode InternalRows to UnsafeRows](#apply).
+`UnsafeProjection` is an [extension](#contract) of the [Projection](Projection.md) abstraction for [projection functions](#implementations) from [InternalRows to (produce) UnsafeRows](#apply).
 
 ```text
-UnsafeProjection: InternalRow =[apply]=> UnsafeRow
+UnsafeProjection: InternalRow => UnsafeRow
 ```
 
+`UnsafeProjection` is created for [code generated](#createCodeGeneratedObject) and [interpreted](#createInterpretedObject) code evaluation paths (using [UnsafeProjection](#CodeGeneratorWithInterpretedFallback) factory object).
+
 ## Contract
 
-### <span id="apply"> Encoding InternalRow as UnsafeRow
+### Encoding InternalRow as UnsafeRow { #apply }
 
 ```scala
 apply(
@@ -29,29 +31,33 @@ Encodes the given [InternalRow](../InternalRow.md) to an [UnsafeRow](../UnsafeRo
 CodeGeneratorWithInterpretedFallback[Seq[Expression], UnsafeProjection]
 ```
 
-### <span id="createCodeGeneratedObject"> createCodeGeneratedObject
+### createCodeGeneratedObject { #createCodeGeneratedObject }
 
-```scala
-createCodeGeneratedObject(
-  in: Seq[Expression]): UnsafeProjection
-```
+??? note "CodeGeneratorWithInterpretedFallback"
 
-`createCodeGeneratedObject` is part of the [CodeGeneratorWithInterpretedFallback](CodeGeneratorWithInterpretedFallback.md#createCodeGeneratedObject) abstraction.
+    ```scala
+    createCodeGeneratedObject(
+      in: Seq[Expression]): UnsafeProjection
+    ```
 
-`createCodeGeneratedObject`...FIXME
+    `createCodeGeneratedObject` is part of the [CodeGeneratorWithInterpretedFallback](CodeGeneratorWithInterpretedFallback.md#createCodeGeneratedObject) abstraction.
 
-### <span id="createInterpretedObject"> createInterpretedObject
+`createCodeGeneratedObject` [generates an UnsafeProjection](../whole-stage-code-generation/GenerateUnsafeProjection.md#generate) for the given [Expression](Expression.md)s (possibly with [Subexpression Elimination](../subexpression-elimination.md) based on [spark.sql.subexpressionElimination.enabled](../configuration-properties.md#spark.sql.subexpressionElimination.enabled) configuration property).
 
-```scala
-createInterpretedObject(
-  in: Seq[Expression]): UnsafeProjection
-```
+### createInterpretedObject { #createInterpretedObject }
+
+??? note "CodeGeneratorWithInterpretedFallback"
+
+    ```scala
+    createInterpretedObject(
+      in: Seq[Expression]): UnsafeProjection
+    ```
 
-`createInterpretedObject` is part of the [CodeGeneratorWithInterpretedFallback](CodeGeneratorWithInterpretedFallback.md#createInterpretedObject) abstraction.
+    `createInterpretedObject` is part of the [CodeGeneratorWithInterpretedFallback](CodeGeneratorWithInterpretedFallback.md#createInterpretedObject) abstraction.
 
-`createInterpretedObject`...FIXME
+`createInterpretedObject` creates an `UnsafeProjection` for the given [Expression](Expression.md)s.
 
-## <span id="create"> create
+## Creating UnsafeProjection { #create }
 
 ```scala
 create(