Use markdown for documentation (#2166)

* Switch to markdown documentation using roxygen2md::roxygen2md()

* Write new Rd files

* Undo changes that roxygen2md made to the aesthetics macro

* Fix bracketed ranges being treated as links

Author: karawoo

DESCRIPTION

@@ -224,3 +224,4 @@ Collate:
     'zzz.r'
 VignetteBuilder: knitr
 RoxygenNote: 6.0.1
+Roxygen: list(markdown = TRUE)

R/aaa-.r

@@ -4,8 +4,8 @@ NULL
 #' Base ggproto classes for ggplot2
 #'
 #' If you are creating a new geom, stat, position, or scale in another package,
-#' you'll need to extend from \code{ggplot2::Geom}, \code{ggplot2::Stat},
-#' \code{ggplot2::Position}, or \code{ggplot2::Scale}.
+#' you'll need to extend from `ggplot2::Geom`, `ggplot2::Stat`,
+#' `ggplot2::Position`, or `ggplot2::Scale`.
 #'
 #' @seealso ggproto
 #' @keywords internal

R/aes.r

@@ -26,7 +26,7 @@ NULL
 #'
 #' Aesthetic mappings describe how variables in the data are mapped to visual
 #' properties (aesthetics) of geoms. Aesthetic mappings can be set in
-#' \code{\link{ggplot2}} and in individual layers.
+#' [ggplot2()] and in individual layers.
 #'
 #' This function also standardise aesthetic names by performing partial
 #' matching, converting color to colour, and translating old style R names to
@@ -35,7 +35,7 @@ NULL
 #' @param x,y,... List of name value pairs giving aesthetics to map to
 #'   variables. The names for x and y aesthetics are typically omitted because
 #'   they are so common; all other aesthetics must be named.
-#' @seealso See \code{\link{aes_}} for a version of \code{aes} that is
+#' @seealso See [aes_()] for a version of `aes` that is
 #'   more suitable for programming with.
 #' @export
 #' @examples
@@ -106,25 +106,25 @@ is_position_aes <- function(vars) {
 #' Define aesthetic mappings programatically
 #'
 #' Aesthetic mappings describe how variables in the data are mapped to visual
-#' properties (aesthetics) of geoms. \code{\link{aes}} uses non-standard
-#' evaluation to capture the variable names. \code{aes_} and \code{aes_string}
-#' require you to explicitly quote the inputs either with \code{""} for
-#' \code{aes_string()}, or with \code{quote} or \code{~} for \code{aes_()}.
-#' (\code{aes_q} is an alias to \code{aes_}). This makes \code{aes_} and
-#' \code{aes_string} easy to program with.
+#' properties (aesthetics) of geoms. [aes()] uses non-standard
+#' evaluation to capture the variable names. `aes_` and `aes_string`
+#' require you to explicitly quote the inputs either with `""` for
+#' `aes_string()`, or with `quote` or `~` for `aes_()`.
+#' (`aes_q` is an alias to `aes_`). This makes `aes_` and
+#' `aes_string` easy to program with.
 #'
-#' \code{aes_string} and \code{aes_} are particularly useful when writing
+#' `aes_string` and `aes_` are particularly useful when writing
 #' functions that create plots because you can use strings or quoted
 #' names/calls to define the aesthetic mappings, rather than having to use
-#' \code{\link{substitute}} to generate a call to \code{aes()}.
+#' [substitute()] to generate a call to `aes()`.
 #'
-#' I recommend using \code{aes_()}, because creating the equivalents of
-#' \code{aes(colour = "my colour")} or \code{aes{x = `X$1`}}
-#' with \code{aes_string()} is quite clunky.
+#' I recommend using `aes_()`, because creating the equivalents of
+#' `aes(colour = "my colour")` or \code{aes{x = `X$1`}}
+#' with `aes_string()` is quite clunky.
 #'
 #' @param x,y,... List of name value pairs. Elements must be either
 #'   quoted calls, strings, one-sided formulas or constants.
-#' @seealso \code{\link{aes}}
+#' @seealso [aes()]
 #' @export
 #' @examples
 #' # Three ways of generating the same aesthetics

R/annotation-custom.r

@@ -17,7 +17,7 @@ NULL
 #' @param ymin,ymax y location (in data coordinates) giving vertical
 #'   location of raster
 #' @export
-#' @note \code{annotation_custom} expects the grob to fill the entire viewport
+#' @note `annotation_custom` expects the grob to fill the entire viewport
 #' defined by xmin, xmax, ymin, ymax. Grobs with a different (absolute) size
 #' will be center-justified in that region.
 #' Inf values can be used to fill the full plot panel (see examples).

R/annotation-logticks.r

@@ -5,29 +5,29 @@
 #'
 #' @param base the base of the log (default 10)
 #' @param sides a string that controls which sides of the plot the log ticks appear on.
-#'   It can be set to a string containing any of \code{"trbl"}, for top, right,
+#'   It can be set to a string containing any of `"trbl"`, for top, right,
 #'   bottom, and left.
-#' @param short a \code{\link[grid]{unit}} object specifying the length of the
+#' @param short a [grid::unit()] object specifying the length of the
 #'   short tick marks
-#' @param mid a \code{\link[grid]{unit}} object specifying the length of the
+#' @param mid a [grid::unit()] object specifying the length of the
 #'   middle tick marks. In base 10, these are the "5" ticks.
-#' @param long a \code{\link[grid]{unit}} object specifying the length of the
+#' @param long a [grid::unit()] object specifying the length of the
 #'   long tick marks. In base 10, these are the "1" (or "10") ticks.
-#' @param scaled is the data already log-scaled? This should be \code{TRUE}
-#'   (default) when the data is already transformed with \code{log10()} or when
-#'   using \code{scale_y_log10}. It should be \code{FALSE} when using
-#'   \code{coord_trans(y = "log10")}.
+#' @param scaled is the data already log-scaled? This should be `TRUE`
+#'   (default) when the data is already transformed with `log10()` or when
+#'   using `scale_y_log10`. It should be `FALSE` when using
+#'   `coord_trans(y = "log10")`.
 #' @param colour Colour of the tick marks.
 #' @param size Thickness of tick marks, in mm.
-#' @param linetype Linetype of tick marks (\code{solid}, \code{dashed}, etc.)
+#' @param linetype Linetype of tick marks (`solid`, `dashed`, etc.)
 #' @param alpha The transparency of the tick marks.
-#' @param color An alias for \code{colour}.
+#' @param color An alias for `colour`.
 #' @param ... Other parameters passed on to the layer
 #'
 #' @export
-#' @seealso \code{\link{scale_y_continuous}}, \code{\link{scale_y_log10}} for log scale
+#' @seealso [scale_y_continuous()], [scale_y_log10()] for log scale
 #'   transformations.
-#' @seealso \code{\link{coord_trans}} for log coordinate transformations.
+#' @seealso [coord_trans()] for log coordinate transformations.
 #'
 #' @examples
 #' # Make a log-log plot (without log ticks)

R/annotation-map.r

@@ -6,7 +6,7 @@ NULL
 #' Display a fixed map on a plot.
 #'
 #' @param map data frame representing a map.  Most map objects can be
-#'   converted into the right format by using \code{\link{fortify}}
+#'   converted into the right format by using [fortify()]
 #' @param ... other arguments used to modify aesthetics
 #' @export
 #' @examples

R/annotation-raster.r

@@ -4,7 +4,7 @@ NULL
 
 #' Annotation: high-performance rectangular tiling
 #'
-#' This is a special version of \code{\link{geom_raster}} optimised for static
+#' This is a special version of [geom_raster()] optimised for static
 #' annotations that are the same in every panel. These annotations will not
 #' affect scales (i.e. the x and y axes will not grow to cover the range
 #' of the raster, and the raster must already have its own colours). This
@@ -15,7 +15,7 @@ NULL
 #'   location of raster
 #' @param ymin,ymax y location (in data coordinates) giving vertical
 #'   location of raster
-#' @param interpolate If \code{TRUE} interpolate linearly, if \code{FALSE}
+#' @param interpolate If `TRUE` interpolate linearly, if `FALSE`
 #'   (the default) don't interpolate.
 #' @export
 #' @examples

R/autolayer.r

@@ -1,14 +1,14 @@
 #' Create a ggplot layer appropriate to a particular data type
 #'
-#' \code{autolayer} uses ggplot2 to draw a particular layer for an object of a
+#' `autolayer` uses ggplot2 to draw a particular layer for an object of a
 #' particular class in a single command. This defines the S3 generic that
 #' other classes and packages can extend.
 #'
 #' @param object an object, whose class will determine the behaviour of autolayer
 #' @param ... other arguments passed to specific methods
 #' @return a ggplot layer
 #' @export
-#' @seealso \code{\link{autoplot}}, \code{\link{ggplot}} and \code{\link{fortify}}
+#' @seealso [autoplot()], [ggplot()] and [fortify()]
 autolayer <- function(object, ...) {
   UseMethod("autolayer")
 }

R/autoplot.r

@@ -1,14 +1,14 @@
 #' Create a complete ggplot appropriate to a particular data type
 #'
-#' \code{autoplot} uses ggplot2 to draw a particular plot for an object of a
+#' `autoplot` uses ggplot2 to draw a particular plot for an object of a
 #' particular class in a single command. This defines the S3 generic that
 #' other classes and packages can extend.
 #'
 #' @param object an object, whose class will determine the behaviour of autoplot
 #' @param ... other arguments passed to specific methods
 #' @return a ggplot object
 #' @export
-#' @seealso \code{\link{autolayer}}, \code{\link{ggplot}} and \code{\link{fortify}}
+#' @seealso [autolayer()], [ggplot()] and [fortify()]
 autoplot <- function(object, ...) {
   UseMethod("autoplot")
 }

R/axis-secondary.R

@@ -10,27 +10,27 @@
 #'
 #' @param breaks One of:
 #' \itemize{
-#'   \item{\code{NULL} for no breaks}
-#'   \item{\code{waiver()} for the default breaks computed by the transformation object}
+#'   \item{`NULL` for no breaks}
+#'   \item{`waiver()` for the default breaks computed by the transformation object}
 #'   \item{A numeric vector of positions}
 #'   \item{A function that takes the limits as input and returns breaks as output}
 #' }
 #'
 #' @param labels One of:
 #' \itemize{
-#'   \item{\code{NULL} for no labels}
-#'   \item{\code{waiver()} for the default labels computed by the transformation object}
-#'   \item{A character vector giving labels (must be same length as \code{breaks})}
+#'   \item{`NULL` for no labels}
+#'   \item{`waiver()` for the default labels computed by the transformation object}
+#'   \item{A character vector giving labels (must be same length as `breaks`)}
 #'   \item{A function that takes the breaks as input and returns labels as output}
 #' }
 #'
 #' @details
-#' \code{sec_axis} is used to create the specifications for a secondary axis.
-#' Except for the \code{trans} argument any of the arguments can be set to
-#' \code{derive()} which would result in the secondary axis inheriting the
+#' `sec_axis` is used to create the specifications for a secondary axis.
+#' Except for the `trans` argument any of the arguments can be set to
+#' `derive()` which would result in the secondary axis inheriting the
 #' settings from the primary axis.
 #'
-#' \code{dup_axis} is provide as a shorthand for creating a secondary axis that
+#' `dup_axis` is provide as a shorthand for creating a secondary axis that
 #' is a duplication of the primary axis, effectively mirroring the primary axis.
 #'
 #' @examples

R/coord-.r

@@ -1,40 +1,40 @@
 #' @section Coordinate systems:
 #'
-#' All \code{coord_*} functions (like \code{coord_trans}) return a \code{Coord*}
-#' object (like \code{CoordTrans}). The \code{Coord*} object is responsible for
+#' All `coord_*` functions (like `coord_trans`) return a `Coord*`
+#' object (like `CoordTrans`). The `Coord*` object is responsible for
 #' adjusting the position of overlapping geoms.
 #'
-#' The way that the \code{coord_*} functions work is slightly different from the
-#' \code{geom_*} and \code{stat_*} functions, because a \code{coord_*} function
-#' actually "instantiates" the \code{Coord*} object by creating a descendant,
+#' The way that the `coord_*` functions work is slightly different from the
+#' `geom_*` and `stat_*` functions, because a `coord_*` function
+#' actually "instantiates" the `Coord*` object by creating a descendant,
 #' and returns that.
 #'
-#' Each of the \code{Coord*} objects is a \code{\link{ggproto}} object,
-#' descended from the top-level \code{Coord}.  To create a new type of Coord
+#' Each of the `Coord*` objects is a [ggproto()] object,
+#' descended from the top-level `Coord`.  To create a new type of Coord
 #' object, you typically will want to implement one or more of the following:
 #'
 #' \itemize{
-#'   \item \code{aspect}: Returns the desired aspect ratio for the plot.
-#'   \item \code{labels}: Returns a list containing labels for x and y.
-#'   \item \code{render_fg}: Renders foreground elements.
-#'   \item \code{render_bg}: Renders background elements.
-#'   \item \code{render_axis_h}: Renders the horizontal axes.
-#'   \item \code{render_axis_v}: Renders the vertical axes.
-#'   \item \code{range}: Returns the x and y ranges
-#'   \item \code{train}: Return the trained scale ranges.
-#'   \item \code{transform}: Transforms x and y coordinates.
-#'   \item \code{distance}: Calculates distance.
-#'   \item \code{is_linear}: Returns \code{TRUE} if the coordinate system is
-#'     linear; \code{FALSE} otherwise.
+#'   \item `aspect`: Returns the desired aspect ratio for the plot.
+#'   \item `labels`: Returns a list containing labels for x and y.
+#'   \item `render_fg`: Renders foreground elements.
+#'   \item `render_bg`: Renders background elements.
+#'   \item `render_axis_h`: Renders the horizontal axes.
+#'   \item `render_axis_v`: Renders the vertical axes.
+#'   \item `range`: Returns the x and y ranges
+#'   \item `train`: Return the trained scale ranges.
+#'   \item `transform`: Transforms x and y coordinates.
+#'   \item `distance`: Calculates distance.
+#'   \item `is_linear`: Returns `TRUE` if the coordinate system is
+#'     linear; `FALSE` otherwise.
 #'
-#'   \item \code{setup_params(data)}: Allows the coordinate system to inspect
+#'   \item `setup_params(data)`: Allows the coordinate system to inspect
 #'     all layers and return a list of additional parameters that vary based on
 #'     the data. These parameters are currently only passed to the other
-#'     setup functions and \code{train()}.
-#'   \item \code{setup_data(data, params)}: Allows the coordinate system to
+#'     setup functions and `train()`.
+#'   \item `setup_data(data, params)`: Allows the coordinate system to
 #'     manipulate the plot data. Should return list of data frames.
-#'   \item \code{setup_layout(layout, params)}: Allows the coordinate
-#'     system to manipulate the \code{layout} data frame which assigns
+#'   \item `setup_layout(layout, params)`: Allows the coordinate
+#'     system to manipulate the `layout` data frame which assigns
 #'     data to panels and scales.
 #' }
 #'

R/coord-cartesian-.r

@@ -6,9 +6,9 @@
 #' change the underlying data like setting limits on a scale will.
 #'
 #' @param xlim,ylim Limits for the x and y axes.
-#' @param expand If \code{TRUE}, the default, adds a small expansion factor to
-#'   the limits to ensure that data and axes don't overlap. If \code{FALSE},
-#'   limits are taken exactly from the data or \code{xlim}/\code{ylim}.
+#' @param expand If `TRUE`, the default, adds a small expansion factor to
+#'   the limits to ensure that data and axes don't overlap. If `FALSE`,
+#'   limits are taken exactly from the data or `xlim`/`ylim`.
 #' @export
 #' @examples
 #' # There are two ways of zooming the plot display: with scales or

R/coord-fixed.r

@@ -3,14 +3,14 @@
 #' A fixed scale coordinate system forces a specified ratio between the
 #' physical representation of data units on the axes. The ratio represents the
 #' number of units on the y-axis equivalent to one unit on the x-axis. The
-#' default, \code{ratio = 1}, ensures that one unit on the x-axis is the same
+#' default, `ratio = 1`, ensures that one unit on the x-axis is the same
 #' length as one unit on the y-axis. Ratios higher than one make units on the
 #' y axis longer than units on the x-axis, and vice versa. This is similar to
-#' \code{\link[MASS]{eqscplot}}, but it works for all types of graphics.
+#' [MASS::eqscplot()], but it works for all types of graphics.
 #'
 #' @export
 #' @inheritParams coord_cartesian
-#' @param ratio aspect ratio, expressed as \code{y / x}
+#' @param ratio aspect ratio, expressed as `y / x`
 #' @examples
 #' # ensures that the ranges of axes are equal to the specified ratio by
 #' # adjusting the plot aspect ratio

R/coord-map.r

@@ -1,9 +1,9 @@
 #' Map projections
 #'
-#' \code{coord_map} projects a portion of the earth, which is approximately
+#' `coord_map` projects a portion of the earth, which is approximately
 #' spherical, onto a flat 2D plane using any projection defined by the
-#' \code{mapproj} package. Map projections do not, in general, preserve straight
-#' lines, so this requires considerable computation. \code{coord_quickmap} is a
+#' `mapproj` package. Map projections do not, in general, preserve straight
+#' lines, so this requires considerable computation. `coord_quickmap` is a
 #' quick approximation that does preserve straight lines. It works best for
 #' smaller areas closer to the equator.
 #'
@@ -15,19 +15,19 @@
 #' 0. For regions that span only a few degrees and are not too close to the
 #' poles, setting the aspect ratio of the plot to the appropriate lat/lon ratio
 #' approximates the usual mercator projection. This is what
-#' \code{coord_quickmap} does, and is much faster (particularly for complex
-#' plots like \code{\link{geom_tile}}) at the expense of correctness.
+#' `coord_quickmap` does, and is much faster (particularly for complex
+#' plots like [geom_tile()]) at the expense of correctness.
 #'
 #' @param projection projection to use, see
-#'    \code{\link[mapproj]{mapproject}} for list
+#'    [mapproj::mapproject()] for list
 #' @param ...,parameters Other arguments passed on to
-#'   \code{\link[mapproj]{mapproject}}. Use \code{...} for named parameters to
-#'   the projection, and \code{parameters} for unnamed parameters.
-#'   \code{...} is ignored if the \code{parameters} argument is present.
+#'   [mapproj::mapproject()]. Use `...` for named parameters to
+#'   the projection, and `parameters` for unnamed parameters.
+#'   `...` is ignored if the `parameters` argument is present.
 #' @param orientation projection orientation, which defaults to
-#'   \code{c(90, 0, mean(range(x)))}.  This is not optimal for many
+#'   `c(90, 0, mean(range(x)))`.  This is not optimal for many
 #'   projections, so you will have to supply your own. See
-#'   \code{\link[mapproj]{mapproject}} for more information.
+#'   [mapproj::mapproject()] for more information.
 #' @param xlim,ylim Manually specific x/y limits (in degrees of
 #'   longitude/latitude)
 #' @export

R/coord-munch.r

@@ -4,8 +4,8 @@
 #' so they can be transformed independently. Used inside geom functions.
 #'
 #' @param coord Coordinate system definition.
-#' @param data Data set to transform - should have variables \code{x} and
-#'   \code{y} are chopped up into small pieces (as defined by \code{group}).
+#' @param data Data set to transform - should have variables `x` and
+#'   `y` are chopped up into small pieces (as defined by `group`).
 #'   All other variables are duplicated as needed.
 #' @param range Panel range specification.
 #' @param segment_length Target segment length

R/coord-polar.r

@@ -3,7 +3,7 @@
 #' The polar coordinate system is most commonly used for pie charts, which
 #' are a stacked bar chart in polar coordinates.
 #'
-#' @param theta variable to map angle to (\code{x} or \code{y})
+#' @param theta variable to map angle to (`x` or `y`)
 #' @param start offset of starting point from 12 o'clock in radians
 #' @param direction 1, clockwise; -1, anticlockwise
 #' @export

R/coord-transform.r

@@ -1,15 +1,15 @@
 #' Transformed Cartesian coordinate system
 #'
-#' \code{coord_trans} is different to scale transformations in that it occurs after
+#' `coord_trans` is different to scale transformations in that it occurs after
 #' statistical transformation and will affect the visual appearance of geoms - there is
 #' no guarantee that straight lines will continue to be straight.
 #'
 #' Transformations only work with continuous values: see
-#' \code{\link[scales]{trans_new}} for list of transformations, and instructions
+#' [scales::trans_new()] for list of transformations, and instructions
 #' on how to create your own.
 #'
 #' @param x,y transformers for x and y axes
-#' @param xtrans,ytrans Deprecated; use \code{x} and \code{y} instead.
+#' @param xtrans,ytrans Deprecated; use `x` and `y` instead.
 #' @param limx,limy limits for x and y axes. (Named so for backward
 #'    compatibility)
 #' @export