typelevel#385 - document chaing with and without using a thrush

build.sbt

@@ -151,7 +151,8 @@ lazy val docs = project
   .settings(sparkMlDependencies(sparkVersion, Compile))
   .settings(
     addCompilerPlugin("org.typelevel" % "kind-projector" % "0.13.2" cross CrossVersion.full),
-    scalacOptions += "-Ydelambdafy:inline"
+    scalacOptions += "-Ydelambdafy:inline",
+    libraryDependencies += "org.typelevel" %% "mouse" % "1.2.1"
   )
   .dependsOn(dataset, cats, ml)
 

docs/FeatureOverview.md

@@ -59,6 +59,7 @@ val aptTypedDs2 = aptDs.typed
 ```
 
 ## Typesafe column referencing
+
 This is how we select a particular column from a `TypedDataset`:
 
 ```scala mdoc
@@ -646,6 +647,34 @@ withCityInfo.select(
 ).as[AptPriceCity].show().run
 ```
 
+### Chained Joins
+
+Joins, or any similar operation, may be chained using a thrush combinator removing the need for intermediate values.  Instead of:
+
+```scala mdoc
+val withBedroomInfoInterim = aptTypedDs.join(citiInfoTypedDS).inner { aptTypedDs('city) === citiInfoTypedDS('name) }
+val withBedroomInfo = withBedroomInfoInterim 
+  .join(bedroomStats).left { withBedroomInfoInterim.col('_1).field('city) === bedroomStats('city)}
+
+withBedroomInfo.show().run()
+```
+
+you can use thrush from [mouse](https://github.com/typelevel/mouse):
+
+```scala
+libraryDependencies += "org.typelevel" %% "mouse" % "1.2.1"
+```
+
+```scala mdoc
+import mouse.all._
+
+val withBedroomInfo = aptTypedDs.join(citiInfoTypedDS).inner { aptTypedDs('city) === citiInfoTypedDS('name) }
+  .thrush( interim => join(bedroomStats).left { interim.col('_1).field('city) === bedroomStats('city)} )
+
+withBedroomInfo.show().run()
+```
+
+
 ```scala mdoc:invisible
 spark.stop()
 ```