From 470649f18f94277d673d64275fc70b368ec9c5f5 Mon Sep 17 00:00:00 2001
From: Anshul Singhvi <anshulsinghvi@gmail.com>
Date: Tue, 14 May 2024 21:32:03 +0400
Subject: [PATCH] as/polygonize_docs

---
 src/methods/polygonize.jl | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/src/methods/polygonize.jl b/src/methods/polygonize.jl
index 01ff42647..acb31b91f 100644
--- a/src/methods/polygonize.jl
+++ b/src/methods/polygonize.jl
@@ -2,12 +2,15 @@
 
 export polygonize
 
-# The methods in this file are able to convert a raster image into a set of polygons,
-# by contour detection using a clockwise Moore neighborhood method.
+#=
+The methods in this file are able to convert a raster image into a set of polygons,
+by contour detection using a clockwise Moore neighborhood method.
+
+The resulting polygons are snapped to the boundaries of the cells of the input raster,
+so they will look different from traditional contours from a plotting package.
 
 ## Example
 
-#=
 Here's a basic example, using the `Makie.peaks()` function.  First, let's investigate the nature of the function:
 
 ```@example polygonize
@@ -32,14 +35,13 @@ which would provide two distinct polyogns with holes.
 ```@example polygonize
 polygons = polygonize(xs, ys, 0.8 .< zs .< 3.2)
 ```
-This returns a list of `GeometryBasics.Polygon`, which can be plotted immediately, 
-or wrapped directly in a `GeometryBasics.MultiPolygon`.  Let's see how these look:
+This returns a `GI.MultiPolygon`, which is directly plottable.  Let's see how these look:
 
 ```@example polygonize
 f, a, p = poly(polygons; label = "Polygonized polygons", axis = (; aspect = DataAspect()))
 ```
 
-Finally, let's plot the Makie contour lines on top, to see how well the polygonization worked:
+Finally, let's plot the Makie contour lines on top, to see how the polygonization compares:
 ```@example polygonize
 contour!(a, xs, ys, zs; labels = true, levels = [0.8, 3.2], label = "Contour lines")
 f
@@ -64,18 +66,20 @@ For other matrix eltypes, function `f` should return `true` or `false`
 based on the matrix values, translating to inside or outside the polygons.
 These will return a single `MultiPolygon` of the `true` values. 
 
-For `AbtractArray{<:Integer}` multiple `multipolygon`s are calculated
-for each value in the array (or passed in `values` keyword), and returned
-as a `FeatureCollection`.
+For `AbtractArray{<:Integer}`, a `multipolygon` is calculated
+for each value in the array (or passed in `values` keyword), 
+and these multipolygons and their associated values are returned
+as a `FeatureCollection`.  You can convert this into a DataFrame
+by calling `DataFrame(polygonize(...))`.
 
-If `xs` and `ys` are ranges, they are used as the pixel center points.
-If they are `Vector` of `Tuple` they are used as the lower and upper bounds of each pixel.
+If `xs` and `ys` are ranges, they are used as the pixel/cell center points.
+If they are `Vector` of `Tuple` they are used as the lower and upper bounds of each pixel/cell.
 
 # Keywords
 
 - `minpoints`: ignore polygons with less than `minpoints` points.
 - `values`: the values to turn into polygons for `Integer` arrays. 
-    By default these are `union(A)`
+    By default these are `unique(A)`.
 
 # Example