add missing docstrings for most methods that are exported from Makie (#…

…51)

Also add "See also" for AlignModes

Co-authored-by: Julius Krumbiegel <22495855+jkrumbiegel@users.noreply.github.com>

src/gridlayout.jl

@@ -229,6 +229,12 @@ function validategridlayout(gl::GridLayout)
     end
 end
 
+"""
+    with_updates_suspended(f::Function, gl::GridLayout; update = true)
+
+Disable layout updates for `gl` and call the function `f`. If `update` is true,
+force a layout update after `f` returns.
+"""
 function with_updates_suspended(f::Function, gl::GridLayout; update = true)
     prev_block_value = gl.block_updates
     gl.block_updates = true
@@ -560,6 +566,11 @@ function Base.isempty(gl::GridLayout, dir::GridDir, i::Integer)
     end
 end
 
+"""
+    trim!(gl::GridLayout)
+
+Remove empty rows and columns from `gl`.
+"""
 function trim!(gl::GridLayout)
     irow = firstrow(gl)
     while irow <= lastrow(gl) && nrows(gl) > 1
@@ -1579,7 +1590,17 @@ function Base.setindex!(gp::GridPosition, element, rows, cols, side = Inner())
     element
 end
 
+"""
+    nrows(g::GridLayout)
+
+Return the number of rows in `g`.
+"""
 nrows(g::GridLayout) = size(g)[1]
+"""
+    ncols(g::GridLayout)
+
+Return the number of columns in `g`.
+"""
 ncols(g::GridLayout) = size(g)[2]
 Base.size(g::GridLayout) = g.size
 offsets(g::GridLayout) = g.offsets
@@ -1670,6 +1691,15 @@ function contents(g::GridSubposition; exact = false)
     contents(layout[g.rows, g.cols, g.side], exact = exact)
 end
 
+"""
+    content(g::Union{GridPosition,GridSubposition})
+
+Return the one object placed in the `GridLayout` at the `Span` and `Side`
+stored in the `GridPosition` `g`. If there is more than one object at that
+position, throw an error.
+
+See also `contents`.
+"""
 function content(g::Union{GridPosition,GridSubposition})
     cs = contents(g, exact = true)
     if length(cs) == 1

src/helpers.jl

@@ -113,6 +113,12 @@ right(rect::Rect{2}) = maximum(rect)[1]
 bottom(rect::Rect{2}) = minimum(rect)[2]
 top(rect::Rect{2}) = maximum(rect)[2]
 
+"""
+    BBox(left::Real, right::Real, bottom::Real, top::Real)
+
+Convenience constructor to create a `Rect2` with left, right, bottom and top
+extent instead of the usual origin, widths combination.
+"""
 function BBox(left::T1, right::T2, bottom::T3, top::T4) where {T1 <: Real, T2 <: Real, T3 <: Real, T4 <: Real}
     T = promote_type(T1, T2, T3, T4, Float32) # Float32 to skip Int outputs
     return BBox(T, left, right, bottom, top)

src/types.jl

@@ -59,15 +59,40 @@ mutable struct GridContent{G} # G should be GridLayout but can't be used before
     reportedsize_handle::Optional{Function}
 end
 
-"AlignMode that excludes the protrusions from the bounding box."
+"""
+AlignMode that excludes the protrusions from the bounding box. Construct with
+`Inside()`.
+
+See also `Outside` and `Mixed`.
+"""
 struct Inside end
 
-"AlignMode that includes the protrusions within the bounding box, plus paddings."
+"""
+AlignMode that includes the protrusions within the bounding box, plus paddings.
+
+See also `Inside` and `Mixed`.
+"""
 struct Outside
     padding::RectSides{Float32}
 end
+
+"""
+    Outside()
+
+Construct an `Outside` AlignMode with no padding.
+"""
 Outside() = Outside(0f0)
+"""
+    Outside(padding::Real)
+
+Construct an `Outside` AlignMode with equal padding on all sides.
+"""
 Outside(padding::Real) = Outside(RectSides{Float32}(padding, padding, padding, padding))
+"""
+    Outside(left::Real, right::Real, bottom::Real, top::Real)
+
+Construct an `Outside` AlignMode with different paddings on each side.
+"""
 Outside(left::Real, right::Real, bottom::Real, top::Real) =
     Outside(RectSides{Float32}(left, right, bottom, top))
 
@@ -81,13 +106,25 @@ struct Protrusion
 end
 
 """
-AlignMode that is Inside where padding is Nothing, Outside where it is Real, and
-overrides the protrusion with a fixed value where it is a `Protrusion`.
+AlignMode that is `Inside` where `padding` is `Nothing`, `Outside` where it is
+`Real`, and overrides the protrusion with a fixed value where it is a
+`Protrusion`.
+
+See also `Inside` and `Outside`.
 """
 struct Mixed
     sides::RectSides{Union{Nothing, Float32, Protrusion}}
 end
 
+"""
+    Mixed(; left = nothing, right = nothing, bottom = nothing, top = nothing)
+
+Construct a `Mixed` AlignMode, which has different behavior on each side.
+Arguments that are `nothing` will exclude protrusions from the bounding box on
+that side. Those that are real numbers will be padded by that amount and
+include protrusions from the bounding box on that side. Arguments that are
+`Protrusion` will override the protrusion with a fixed value.
+"""
 function Mixed(; left = nothing, right = nothing, bottom = nothing, top = nothing)
     sides = map((left, right, bottom, top)) do side
         (side === nothing || side isa Protrusion) ? side : Float32(side)