From 314cf164ebb51ecefd67e86f4c03d0688bb4f4f7 Mon Sep 17 00:00:00 2001
From: ffreyer <frederic481994@hotmail.de>
Date: Sat, 29 Jul 2023 14:19:54 +0200
Subject: [PATCH] add docstrings + fix name

---
 MakieCore/src/conversion.jl | 57 +++++++++++++++++++++++++++++++++----
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/MakieCore/src/conversion.jl b/MakieCore/src/conversion.jl
index 38e77fc7d03..93c6daecb11 100644
--- a/MakieCore/src/conversion.jl
+++ b/MakieCore/src/conversion.jl
@@ -31,30 +31,75 @@ struct NoConversion <: ConversionTrait end
 conversion_trait(::Type) = NoConversion()
 convert_arguments(::NoConversion, args...) = args
 
+"""
+    PointBased() <: ConversionTrait
+
+Plots with the `PointBased` trait convert their input data to a
+`Vector{Point{D, Float32}}`.
+"""
 struct PointBased <: ConversionTrait end
 conversion_trait(::Type{<: XYBased}) = PointBased()
 conversion_trait(::Type{<: Text}) = PointBased()
 
+"""
+    GridBased <: ConversionTrait
+
+GridBased is an abstract conversion trait for data that exists on a grid.
+
+Child types: [`VertexBasedGrid`](@ref), [`CellBasedGrid`](@ref)
+See also: [`ImageLike`](@ref)
+Used for: Scatter, Lines
+"""
 abstract type GridBased <: ConversionTrait end
 
+"""
+    VertexBasedGrid() <: GridBased <: ConversionTrait
+
+Plots with the `VertexBasedGrid` trait convert their input data to
+`(xs::Vector{Float32}, ys::Vector{Float32}, zs::Matrix{Float32})` such that
+`(length(xs), length(ys)) == size(zs)`, or
+`(xs::Matrix{Float32}, ys::Matrix{Float32}, zs::Matrix{Float32})` such that
+`size(xs) == size(ys) == size(zs)`.
+
+See also: [`CellBasedGrid`](@ref), [`ImageLike`](@ref)
+Used for: Surface
+"""
 struct VertexBasedGrid <: GridBased end
 conversion_trait(::Type{<: Surface}) = VertexBasedGrid()
-# [Point3f(xs[i], ys[j], zs[i, j]) for i in axes(zs, 1), j in axes(zs, 2)]
 
+"""
+    CellBasedGrid() <: GridBased <: ConversionTrait
+
+Plots with the `CellBasedGrid` trait convert their input data to
+`(xs::Vector{Float32}, ys::Vector{Float32}, zs::Matrix{Float32})` such that
+`(length(xs), length(ys)) == size(zs) .+ 1`. After the conversion the x and y
+values represent the edges of cells corresponding to z values.
+
+See also: [`VertexBasedGrid`](@ref), [`ImageLike`](@ref)
+Used for: Heatmap
+"""
 struct CellBasedGrid <: GridBased end
 conversion_trait(::Type{<: Heatmap}) = CellBasedGrid()
-# [Rect2f(xs[i], ys[j], xs[i+1], ys[j+1]) for i in axes(zs, 1), j in axes(zs, 2)]
 
-struct ImageLike end
+"""
+    ImageLike() <: ConversionTrait
+
+Plots with the `ImageLike` trait convert their input data to
+`(xs::Interval, ys::Interval, zs::Matrix{Float32})` where xs and ys mark the
+limits of a quad containing zs.
+
+See also: [`CellBasedGrid`](@ref), [`VertexBasedGrid`](@ref)
+Used for: Image
+"""
+struct ImageLike <: ConversionTrait end
 conversion_trait(::Type{<: Image}) = ImageLike()
 # Rect2f(xmin, ymin, xmax, ymax)
 
 # Deprecations
 function ContinuousSurface()
-    error("ContinuousSurface has been deprecated. Use `ImageLike()` or `VertexBasedGrid()`")
+    error("ContinuousSurface has been deprecated. Use `ImageLike()` or `VertexBasedGrid()` instead.")
 end
-
-@deprecate DiscreteSurface CellLike()
+@deprecate DiscreteSurface CellBasedGrid()
 
 struct VolumeLike <: ConversionTrait end
 conversion_trait(::Type{<: Volume}) = VolumeLike()
\ No newline at end of file