Merge pull request #192 from stan-dev/markdown-in-roxygen

Use markdown in roxygen

Author: jgabry

DESCRIPTION

@@ -46,3 +46,4 @@ Suggests:
 RoxygenNote: 6.1.1
 VignetteBuilder: knitr
 Encoding: UTF-8
+Roxygen: list(markdown = TRUE)

R/available-module-functions.R

@@ -1,12 +1,12 @@
 #' Get or view the names of available plotting functions
 #'
 #' @export
-#' @param pattern,fixed,invert Passed to \code{\link[base]{grep}}.
+#' @param pattern,fixed,invert Passed to [base::grep()].
 #' @return A possibly empty character vector of function names with several
-#'   additional attributes (for use by a custom print method). If \code{pattern}
+#'   additional attributes (for use by a custom print method). If `pattern`
 #'   is missing then the returned object contains the names of all available
-#'   plotting functions in the \link{MCMC} or \link{PPC} module, depending on
-#'   which function is called. If \code{pattern} is specified then a subset of
+#'   plotting functions in the [MCMC] or [PPC] module, depending on
+#'   which function is called. If `pattern` is specified then a subset of
 #'   function names is returned.
 #'
 #' @examples

R/bayesplot-colors.R

@@ -1,11 +1,10 @@
-#' Set, get, or view color schemes
+#' Set, get, or view **bayesplot** color schemes
 #'
 #' Set, get, or view color schemes. Choose from a preset scheme or create a
 #' custom scheme. See the **Available color schemes** section below for a list
 #' of available scheme names. The **Custom color schemes** section describes how
 #' to specify a custom scheme.
 #'
-#' @md
 #' @name bayesplot-colors
 #' @param scheme For `color_scheme_set()`, either a string naming one of the
 #'   available color schemes or a character vector of _exactly six_ colors
@@ -143,7 +142,6 @@ color_scheme_set <- function(scheme = "blue") {
 }
 
 #' @rdname bayesplot-colors
-#' @md
 #' @export
 #' @param i For `color_scheme_get()`, an optional subset of the integers from `1`
 #'   (lightest) to `6` (darkest) indicating which of the colors in the
@@ -289,9 +287,9 @@ mixed_scheme <- function(scheme1, scheme2) {
   scheme
 }
 
-#' Check if object returned by color_scheme_get() is a mixed scheme
+#' Check if object returned by `color_scheme_get()` is a mixed scheme
 #' @noRd
-#' @param x object returned by color_scheme_get()
+#' @param x object returned by `color_scheme_get()`
 #' @return T/F
 is_mixed_scheme <- function(x) {
   stopifnot(is.list(x))
@@ -300,7 +298,7 @@ is_mixed_scheme <- function(x) {
 
 #' Access a subset of the current scheme colors
 #' @noRd
-#' @param level A character vector of level names scheme_level_names().
+#' @param level A character vector of level names in `scheme_level_names()`.
 #'   The abbreviations "l", "lh", "m", "mh", "d", and "dh" can also be used
 #'   instead of the full names.
 #' @return A character vector of color values.

R/bayesplot-extractors.R

@@ -2,36 +2,34 @@
 #'
 #' Generics and methods for extracting quantities needed for plotting from
 #' various types of model objects. Currently methods are only provided for
-#' stanfit (\pkg{rstan}) and stanreg (\pkg{rstanarm}) objects, but adding new
+#' stanfit (**rstan**) and stanreg (**stanreg**) objects, but adding new
 #' methods should be relatively straightforward.
 #'
 #' @name bayesplot-extractors
 #' @param object The object to use.
 #' @param ... Arguments passed to individual methods.
 #' @param pars An optional character vector of parameter names. For
-#'   \code{nuts_params} these will be NUTS sampler parameter names rather than
-#'   model parameters. If \code{pars} is omitted all parameters are included.
+#'   `nuts_params()` these will be NUTS sampler parameter names rather than
+#'   model parameters. If `pars` is omitted all parameters are included.
 #'
 #' @return
 #' \describe{
-#' \item{\code{log_posterior}}{
-#' \code{log_posterior} methods return a molten data frame (see
-#' \code{\link[reshape2]{melt}}). The data frame should have columns
-#' \code{"Iteration"} (integer), \code{"Chain"} (integer), and \code{"Value"}
-#' (numeric). See \strong{Examples}, below.
+#' \item{`log_posterior()`}{
+#' `log_posterior()` methods return a molten data frame (see [reshape2::melt()]).
+#' The data frame should have columns `"Iteration"` (integer), `"Chain"`
+#' (integer), and `"Value"` (numeric). See **Examples**, below.
 #' }
-#' \item{\code{nuts_params}}{
-#' \code{nuts_params} methods return a molten data frame (see
-#' \code{\link[reshape2]{melt}}). The data frame should have columns
-#' \code{"Parameter"} (factor), \code{"Iteration"} (integer), \code{"Chain"}
-#' (integer), and \code{"Value"} (numeric). See \strong{Examples}, below.
+#' \item{`nuts_params()`}{
+#' `nuts_params()` methods return a molten data frame (see [reshape2::melt()]).
+#' The data frame should have columns `"Parameter"` (factor), `"Iteration"`
+#' (integer), `"Chain"` (integer), and `"Value"` (numeric). See **Examples**, below.
 #' }
-#' \item{\code{rhat}, \code{neff_ratio}}{
+#' \item{`rhat()`, `neff_ratio()`}{
 #' Methods return (named) vectors.
 #' }
 #' }
 #'
-#' @seealso \code{\link{MCMC-nuts}}, \code{\link{MCMC-diagnostics}}
+#' @seealso [MCMC-nuts], [MCMC-diagnostics]
 #'
 #' @examples
 #' \dontrun{
@@ -80,7 +78,7 @@ neff_ratio <- function(object, ...) {
 #' @rdname bayesplot-extractors
 #' @export
 #' @method log_posterior stanfit
-#' @param inc_warmup A logical scalar (defaulting to \code{FALSE}) indicating
+#' @param inc_warmup A logical scalar (defaulting to `FALSE`) indicating
 #'   whether to include warmup draws, if applicable.
 #'
 log_posterior.stanfit <- function(object, inc_warmup = FALSE, ...) {

R/bayesplot-ggplot-themes.R

@@ -1,19 +1,18 @@
-#' Default bayesplot plotting theme
+#' Default **bayesplot** plotting theme
 #'
-#' The \code{\link{theme_default}} function returns the default ggplot
-#' \link{theme} used by the \pkg{bayesplot} plotting functions. See
-#' \code{\link{bayesplot_theme_set}} for details on setting and updating the
-#' plotting theme.
+#' The [theme_default()] function returns the default ggplot
+#' [theme][ggplot2::theme] used by the **bayesplot** plotting functions. See
+#' [bayesplot_theme_set()] for details on setting and updating the plotting
+#' theme.
 #'
 #' @export
 #' @param base_size,base_family Base font size and family (passed to
-#'   \code{\link[ggplot2]{theme_bw}}). It is possible to set
-#'   \code{"bayesplot.base_size"} and \code{"bayesplot.base_family"} via
-#'   \code{\link{options}} to change the defaults, which are \code{12} and
-#'   \code{"serif"}, respectively.
-#' @return A ggplot \link[ggplot2]{theme} object.
+#'   [ggplot2::theme_bw()]). It is possible to set `"bayesplot.base_size"` and
+#'   `"bayesplot.base_family"` via [options()] to change the defaults, which are
+#'   `12` and `"serif"`, respectively.
+#' @return A ggplot [theme][ggplot2::theme] object.
 #'
-#' @seealso \code{\link{bayesplot_theme_set}} to change the ggplot theme.
+#' @seealso [bayesplot_theme_set()] to change the ggplot theme.
 #' @template seealso-colors
 #' @template seealso-helpers
 #'
@@ -62,36 +61,34 @@ theme_default <-
   }
 
 
-#' Get, set, and modify the active bayesplot theme
+#' Get, set, and modify the active **bayesplot** theme
 #'
-#' @description These functions are the \pkg{bayesplot} equivalent to
-#'   \pkg{ggplot2}'s \code{\link[ggplot2]{theme_set}} and friends. They set,
-#'   get, and update the active theme but only apply them to \code{bayesplots}.
-#'   The current/active theme is automatically applied to every \code{bayesplot}
-#'   you draw.
+#' @description These functions are the **bayesplot** equivalent to
+#'   **ggplot2**'s [ggplot2::theme_set()] and friends. They set, get, and update
+#'   the active theme but only apply them to `bayesplots`. The current/active
+#'   theme is automatically applied to every `bayesplot` you draw.
 #'
-#'   Use \code{bayesplot_theme_get} to get the current \pkg{bayesplot} theme,
-#'   and \code{bayesplot_theme_set} to change it. \code{bayesplot_theme_update}
-#'   and \code{bayesplot_theme_replace} are shorthands for changing individual
-#'   elements.
+#'   Use `bayesplot_theme_get()` to get the current **bayesplot** theme and
+#'   `bayesplot_theme_set()` to set a new theme. `bayesplot_theme_update()` and
+#'   `bayesplot_theme_replace()` are shorthands for changing individual elements.
 #'
-#' @details \code{bayesplot_theme_set} and friends only apply to
-#'   \code{bayesplots}. However, \code{ggplot2::theme_set} can also be used to
-#'   change the \pkg{bayesplot} theme. Currently, setting a theme with
-#'   \code{ggplot2::theme_set} (other than the \pkg{ggplot2} default
-#'   \code{\link[ggplot2]{theme_grey}}) will override the \pkg{bayesplot} theme.
+#' @details `bayesplot_theme_set()` and friends only apply to `bayesplots`.
+#'   However, [ggplot2::theme_set()] can also be used to change the
+#'   **bayesplot** theme. Currently, setting a theme with `ggplot2::theme_set()`
+#'   (other than the **ggplot2** default [ggplot2::theme_grey()]) will override
+#'   the **bayesplot** theme.
 #'
 #' @export
 #' @param new The new theme (list of theme elements) to use. This is analogous
-#'   to the \code{new} argument to \code{\link[ggplot2]{theme_set}}.
+#'   to the `new` argument to [ggplot2::theme_set()].
 #' @param ... A named list of theme settings.
 #'
-#' @return \code{bayesplot_theme_get} returns the current theme. The other three
-#'   functions (set, update, replace) invisibly return the \emph{previous} theme
+#' @return `bayesplot_theme_get()` returns the current theme. The other three
+#'   functions (set, update, replace) invisibly return the *previous* theme
 #'   so it can be saved and easily restored later. This is the same behavior as
-#'   the \pkg{ggplot2} versions of these functions.
+#'   the **ggplot2** versions of these functions.
 #'
-#' @seealso \code{\link{theme_default}} for the default \pkg{bayesplot} theme.
+#' @seealso [theme_default()] for the default **bayesplot** theme.
 #' @template seealso-helpers
 #' @template seealso-colors
 #'