From 47692756dee5e7c4a7c69630c88bd4af8311e05b Mon Sep 17 00:00:00 2001
From: Colin Woodbury <colingw@gmail.com>
Date: Tue, 31 Oct 2017 08:51:43 -0700
Subject: [PATCH] Add `ClipToGrid` docstrings

---
 .../geotrellis/spark/clip/ClipToGrid.scala    | 32 ++++++++++++++++++-
 .../spark/clip/FeatureClipToGridMethods.scala |  1 +
 .../clip/GeometryClipToGridMethods.scala      |  1 +
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/spark/src/main/scala/geotrellis/spark/clip/ClipToGrid.scala b/spark/src/main/scala/geotrellis/spark/clip/ClipToGrid.scala
index 092c8e6ac5..83a67a611f 100644
--- a/spark/src/main/scala/geotrellis/spark/clip/ClipToGrid.scala
+++ b/spark/src/main/scala/geotrellis/spark/clip/ClipToGrid.scala
@@ -25,6 +25,36 @@ import geotrellis.vector._
 import com.vividsolutions.jts.geom.prep.{PreparedGeometry, PreparedGeometryFactory}
 import org.apache.spark.rdd._
 
+/**
+  * These functions perform the following transformation:
+  *
+  * {{{
+  * RDD[Geometry] => RDD[(SpatialKey, Geometry)]
+  * }}}
+  *
+  * such that each original [[Geometry]] is clipped in some way. By default,
+  * this clips them to fit inside the [[Extent]] of each [[SpatialKey]]
+  * they touch.
+  *
+  * If you'd like more customized clipping behaviour, you can compose
+  * over the [[clipFeatureToExtent]] function below, or write your own
+  * entirely, while following its type signature. That can then be passed
+  * into the appropriate `apply` method below.
+  *
+  * A variety of overloads are provided here to help you work with either
+  * [[Geometry]] or [[Feature]]. The injected
+  *
+  * {{{
+  * RDD[Geometry].clipToGrid: LayoutDefinition => RDD[(SpatialKey, Geometry)]
+  * }}}
+  *
+  * may also be preferable to you.
+  *
+  * '''Note:''' If your custom clipping function relies on [[Predicates]],
+  * note that its method `coveredBy` will always return `true` if your Geometry
+  * fits inside the passed-in [[Extent]]. Please avoid writing clipping
+  * functions that do non-sensical things.
+  */
 object ClipToGrid {
   /** Trait which contains methods to be used in determining
     * the most optimal way to clip geometries and features
@@ -33,7 +63,7 @@ object ClipToGrid {
   trait Predicates extends Serializable {
     /** Returns true if the feature geometry covers the passed in extent */
     def covers(e: Extent): Boolean
-    /** Returns true if the feature geometry is covered bythe passed in extent */
+    /** Returns true if the feature geometry is covered by the passed in extent */
     def coveredBy(e: Extent): Boolean
   }
 
diff --git a/spark/src/main/scala/geotrellis/spark/clip/FeatureClipToGridMethods.scala b/spark/src/main/scala/geotrellis/spark/clip/FeatureClipToGridMethods.scala
index 24682ef9a0..0af934d7f9 100644
--- a/spark/src/main/scala/geotrellis/spark/clip/FeatureClipToGridMethods.scala
+++ b/spark/src/main/scala/geotrellis/spark/clip/FeatureClipToGridMethods.scala
@@ -23,6 +23,7 @@ import geotrellis.vector._
 
 import org.apache.spark.rdd._
 
+/** See [[ClipToGrid]]. */
 trait FeatureClipToGridMethods[G <: Geometry, D] extends MethodExtensions[RDD[Feature[G, D]]] {
   def clipToGrid(layout: LayoutDefinition): RDD[(SpatialKey, Feature[Geometry, D])] =
     ClipToGrid(self, layout)
diff --git a/spark/src/main/scala/geotrellis/spark/clip/GeometryClipToGridMethods.scala b/spark/src/main/scala/geotrellis/spark/clip/GeometryClipToGridMethods.scala
index 3dbc5afb9a..e8f11f954d 100644
--- a/spark/src/main/scala/geotrellis/spark/clip/GeometryClipToGridMethods.scala
+++ b/spark/src/main/scala/geotrellis/spark/clip/GeometryClipToGridMethods.scala
@@ -23,6 +23,7 @@ import geotrellis.vector._
 
 import org.apache.spark.rdd._
 
+/** See [[ClipToGrid]]. */
 trait GeometryClipToGridMethods[G <: Geometry] extends MethodExtensions[RDD[G]] {
   def clipToGrid(layout: LayoutDefinition): RDD[(SpatialKey, Geometry)] =
     ClipToGrid(self, layout)