Merge pull request #3628 from anowacki/an/annotation-docs

Document use of tuples in annotations attribute

src/arg_desc.jl

@@ -115,7 +115,7 @@ const _arg_desc = KW(
 :colorbar_formatter          => "Function, :scientific, :plain or :auto. A method which converts a number to a string for tick labeling.",
 :legendfont                  => "Font. Font of legend items.",
 :legendtitlefont             => "Font. Font of the legend title.",
-:annotations                 => "(x,y,text) tuple(s).  Can be a single tuple or a list of them.  Text can be String or PlotText (created with `text(args...)`)  Add one-off text annotations at the x,y coordinates.",
+:annotations                 => "(x,y,text) tuple(s).  Can be a single tuple or a list of them.  Text can be String, PlotText (created with `text(args...)`), or a tuple of arguments to `text` (e.g., `(\"Label\", 8, :red, :top)`).  Add one-off text annotations at the x,y coordinates.",
 :annotationfontfamily        => "String or Symbol. Font family of annotations.",
 :annotationfontsize          => "Integer. Font pointsize of annotations.",
 :annotationhalign            => "Symbol. horizontal alignment of annotations, :hcenter, :left, :right or :center.",

src/examples.jl

@@ -370,10 +370,19 @@ const _examples = PlotExample[
         "Annotations",
         """
         The `annotations` keyword is used for text annotations in data-coordinates.  Pass in a
-        tuple (x,y,text) or a vector of annotations.  `annotate!(ann)` is shorthand for `plot!(;
-        annotation=ann)`.  Series annotations are used for annotating individual data points.
-        They require only the annotation... x/y values are computed.  A `PlotText` object can be
-        build with the method `text(string, attr...)`, which wraps font and color attributes.
+        tuple `(x, y, text)`, or a vector of annotations, each of which is a tuple of `x`, `y`
+        and `text`.
+        `text` may be a simple `String`, or a `PlotText` object, which can be
+        built with the method `text(string, attrs...)`.
+        This wraps font and color attributes and allows you to set text styling.
+        `text` may also be a tuple `(string, attrs...)` of arguments which are passed
+        to `Plots.text`.
+
+        `annotate!(ann)` is shorthand for `plot!(; annotation=ann)`.
+
+        Series annotations are used for annotating individual data points.
+        They require only the annotation; x/y values are computed.  Series annotations
+        require either plain `String`s or `PlotText` objects.
         """,
         [
             :(
@@ -385,11 +394,11 @@ const _examples = PlotExample[
                         leg = false,
                     )
                     annotate!([
-                        (5, y[5], Plots.text("this is #5", 16, :red, :center)),
+                        (5, y[5], ("this is #5", 16, :red, :center)),
                         (
                             10,
                             y[10],
-                            Plots.text("this is #10", :right, 20, "courier"),
+                            ("this is #10", :right, 20, "courier"),
                         ),
                     ])
                     scatter!(

src/shorthands.jl

@@ -453,12 +453,14 @@ Add annotations to an existing plot.
 # Arguments
 
 - `anns`: An `AbstractVector` of tuples of the form `(x,y,text)`. The `text` object
-          can be a `String` or `PlotText`.
+          can be a `String`, `PlotText` PlotText (created with `text(args...)`),
+          or a tuple of arguments to `text` (e.g., `("Label", 8, :red, :top)`).
 
 # Example
 ```julia-repl
 julia> plot(1:10)
 julia> annotate!([(7,3,"(7,3)"),(3,7,text("hey", 14, :left, :top, :green))])
+julia> annotate!([(4, 4, ("More text", 8, 45.0, :bottom, :red))])
 ```
 """
 annotate!(anns...; kw...)             = plot!(; annotation = anns, kw...)