Improve geom_text documentation (#3753) (#3771)

* Improve geom_text documentation. closes #3753

Author: tereom

R/geom-text.r

@@ -1,21 +1,28 @@
 #' Text
 #'
-#' `geom_text()` adds text directly to the plot. `geom_label()` draws
-#' a rectangle behind the text, making it easier to read.
-#'
-#' Note that the "width" and "height" of a text element are 0, so stacking
-#' and dodging text will not work by default, and axis limits are not
-#' automatically expanded to include all text. Obviously, labels do have
-#' height and width, but they are physical units, not data units. The amount of
-#' space they occupy on the plot is not constant in data units: when you
-#' resize a plot, labels stay the same size, but the size of the axes changes.
+#' Text geoms are useful for labeling plots. They can be used by themselves as
+#' scatterplots or in cobination with other geoms, for example, for labeling
+#' points or for annotating the height of bars. `geom_text()` adds only text
+#' to the plot. `geom_label()` draws a rectangle behind the text, making it
+#' easier to read.
+#'
+#' Note that when you resize a plot, text labels stay the same size, even
+#' though the size of the plot area changes. This happens because the "width"
+#' and "height" of a text element are 0. Obviously, text labels do have height
+#' and width, but they are physical units, not data units. For the same reason,
+#' stacking and dodging text will not work by default, and axis limits are not
+#' automatically expanded to include all text.
 #'
 #' `geom_text()` and `geom_label()` add labels for each row in the
 #' data, even if coordinates x, y are set to single values in the call
 #' to `geom_label()` or `geom_text()`.
 #' To add labels at specified points use [annotate()] with
 #' `annotate(geom = "text", ...)` or `annotate(geom = "label", ...)`.
 #'
+#' To automatically position non-overlapping text labels see the
+#' \href{https://cran.r-project.org/package=ggrepel}{ggrepel}
+#' package.
+#'
 #' @eval rd_aesthetics("geom", "text")
 #' @section `geom_label()`:
 #' Currently `geom_label()` does not support the `angle` aesthetic and
@@ -36,8 +43,14 @@
 #'   displayed as described in `?plotmath`.
 #' @param nudge_x,nudge_y Horizontal and vertical adjustment to nudge labels by.
 #'   Useful for offsetting text from points, particularly on discrete scales.
+#'   Cannot be jointy specified with `position`.
+#' @param position Position adjustment, either as a string, or the result of
+#'  a call to a position adjustment function. Cannot be jointy specified with
+#'  `nudge_x` or `nudge_y`.
 #' @param check_overlap If `TRUE`, text that overlaps previous text in the
-#'   same layer will not be plotted.
+#'   same layer will not be plotted. `check_overlap` happens at draw time and in
+#'   the order of the data. Therefore data should be arranged by the label
+#'   column before calling `geom_label()` or `geom_text()`.
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(wt, mpg, label = rownames(mtcars)))