diff --git a/MakieCore/src/basic_plots.jl b/MakieCore/src/basic_plots.jl
index 9ad23fca395..ff7575b3d24 100644
--- a/MakieCore/src/basic_plots.jl
+++ b/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 [`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 [`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 [`Linestyle`](@ref).
+    """
     linestyle = nothing
     linecap = @inherit linecap
     joinstyle = @inherit joinstyle
diff --git a/src/basic_recipes/makiecore_examples/lines.jl b/src/basic_recipes/makiecore_examples/lines.jl
new file mode 100644
index 00000000000..dfccbdc4ef8
--- /dev/null
+++ b/src/basic_recipes/makiecore_examples/lines.jl
@@ -0,0 +1,49 @@
+function attribute_examples(::Type{Scatter})
+    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
\ No newline at end of file
diff --git a/src/conversions.jl b/src/conversions.jl
index 7b0812abf3d..3447c6ad8a5 100644
--- a/src/conversions.jl
+++ b/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}