Improve linestyle documentation with examples (#3935)

MakieCore/src/basic_plots.jl

@@ -317,7 +317,13 @@ Creates a connected line plot for each element in `(x, y, z)`, `(x, y)` or `posi
     color = @inherit linecolor
     "Sets the width of the line in screen units"
     linewidth = @inherit linewidth
-    "Sets the pattern of the line e.g. `:solid`, `:dot`, `:dashdot`. For custom patterns look at `Linestyle(Number[...])`"
+    """
+    Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`.
+    These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`.
+    For example, `(:dot, :loose)` or `(:dashdot, :dense)`.
+    
+    For custom patterns have a look at [`Makie.Linestyle`](@ref).
+    """
     linestyle = nothing
     "Sets the type of linecap used, i.e. :butt (flat with no extrusion), :square (flat with 0.5 linewidth extrusion) or :round."
     linecap = @inherit linecap
@@ -345,7 +351,13 @@ Plots a line for each pair of points in `(x, y, z)`, `(x, y)`, or `positions`.
     color = @inherit linecolor
     "Sets the width of the line in pixel units"
     linewidth = @inherit linewidth
-    "Sets the pattern of the line e.g. `:solid`, `:dot`, `:dashdot`. For custom patterns look at `Linestyle(Number[...])`"
+    """
+    Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`.
+    These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`.
+    For example, `(:dot, :loose)` or `(:dashdot, :dense)`.
+    
+    For custom patterns have a look at [`Makie.Linestyle`](@ref).
+    """
     linestyle = nothing
     "Sets the type of linecap used, i.e. :butt (flat with no extrusion), :square (flat with 1 linewidth extrusion) or :round."
     linecap = @inherit linecap
@@ -594,7 +606,13 @@ Plots polygons, which are defined by
     strokecolormap = @inherit colormap
     "Sets the width of the outline."
     strokewidth = @inherit patchstrokewidth
-    "Sets the pattern of the line (e.g. `:solid`, `:dot`, `:dashdot`)"
+    """
+    Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`.
+    These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`.
+    For example, `(:dot, :loose)` or `(:dashdot, :dense)`.
+    
+    For custom patterns have a look at [`Makie.Linestyle`](@ref).
+    """
     linestyle = nothing
     linecap = @inherit linecap
     joinstyle = @inherit joinstyle

docs/src/reference/plots/lines.md

@@ -22,27 +22,6 @@ lines!(xs, ys .- 3, linestyle = :dash)
 f
 ```
 
-### Linestyles
-
-```@figure
-f = Figure()
-Axis(f[1, 1])
-
-xs = 0:0.01:10
-ys = 0.5 .* sin.(xs)
-
-for (i, lw) in enumerate([1, 2, 3])
-    lines!(xs, ys .- i/6, linestyle = nothing, linewidth = lw)
-    lines!(xs, ys .- i/6 .- 1, linestyle = :dash, linewidth = lw)
-    lines!(xs, ys .- i/6 .- 2, linestyle = :dot, linewidth = lw)
-    lines!(xs, ys .- i/6 .- 3, linestyle = :dashdot, linewidth = lw)
-    lines!(xs, ys .- i/6 .- 4, linestyle = :dashdotdot, linewidth = lw)
-    lines!(xs, ys .- i/6 .- 5, linestyle = Linestyle([0.5, 1.0, 1.5, 2.5]), linewidth = lw)
-end
-
-f
-```
-
 ### Linecaps and Joinstyles
 
 ```@figure

src/Makie.jl

@@ -183,6 +183,7 @@ include("basic_recipes/wireframe.jl")
 include("basic_recipes/tooltip.jl")
 
 include("basic_recipes/makiecore_examples/scatter.jl")
+include("basic_recipes/makiecore_examples/lines.jl")
 
 # layouting of plots
 include("layouting/transformation.jl")

src/basic_recipes/makiecore_examples/lines.jl

@@ -0,0 +1,49 @@
+function attribute_examples(::Type{Lines})
+    Dict(
+        :linestyle => [
+            Example(
+                code = """
+                    linestyles = [:solid, :dot, :dash, :dashdot, :dashdotdot]
+                    gapstyles = [:normal, :dense, :loose, 10]
+                    fig = Figure()
+                    with_updates_suspended(fig.layout) do
+                        for (i, ls) in enumerate(linestyles)
+                            for (j, gs) in enumerate(gapstyles)
+                                title = gs === :normal ? repr(ls) : "\$((ls, gs))"
+                                ax = Axis(fig[i, j]; title, yautolimitmargin = (0.2, 0.2))
+                                hidedecorations!(ax)
+                                hidespines!(ax)
+                                linestyle = (ls, gs)
+                                for linewidth in 1:3
+                                    lines!(ax, 1:10, fill(linewidth, 10); linestyle, linewidth)
+                                end
+                            end
+                        end
+                    end
+                    fig
+                    """
+            ),
+            Example(
+                code = """
+                    fig = Figure()
+                    patterns = [
+                        [0, 1, 2],
+                        [0, 20, 22],
+                        [0, 2, 4, 12, 14],
+                        [0, 2, 4, 6, 8, 10, 20],
+                        [0, 1, 2, 4, 6, 9, 12],
+                        [0.0, 4.0, 6.0, 9.5],
+                    ]
+                    ax = Axis(fig[1, 1], yautolimitmargin = (0.2, 0.2))
+                    for (i, pattern) in enumerate(patterns)
+                        lines!(ax, [-i, -i], linestyle = Linestyle(pattern), linewidth = 4)
+                        text!(ax, (1.5, -i), text = "Linestyle(\$pattern)",
+                            align = (:center, :bottom), offset = (0, 10))
+                    end
+                    hidedecorations!(ax)
+                    fig
+                    """
+            ),
+        ],
+    )
+end

src/conversions.jl

@@ -927,12 +927,18 @@ end
 A type that can be used as value for the `linestyle` keyword argument
 of plotting functions to arbitrarily customize the linestyle.
 
-The `value` is a vector of positions where the line flips from being drawn or not
-and vice versa. The values of `value` are in units of linewidth.
+The `value` is a vector specifying the boundaries of the dashes in the line.
+Values 1 and 2 demarcate the first dash, values 2 and 3 the first gap, and so on.
+This means that usually, a pattern should have an odd number of values so that there's
+always a gap after a dash.
 
-For example, with `value = [0.0, 4.0, 6.0, 9.5]`
-you start drawing at 0, stop at 4 linewidths, start again at 6, stop at 9.5,
-then repeat with 0 and 9.5 being treated as the same position.
+Here's an example in ASCII code. If we specify `[0, 3, 6, 11, 16]` then we get the following
+pattern:
+
+```
+#  0  3   6   11   16  3  6   11
+#   ---   -----     ---   -----
+```
 """
 struct Linestyle
     value::Vector{Float32}