adjust doc formatting to match other functions better

Author: mjskay

R/as_draws_rvars.R

@@ -8,7 +8,7 @@
 #' @template draws_format-skeleton
 #' @template args-format-nchains
 #'
-#' @details Objects of class `"draws_rvars"` are lists of [rvar] objects. See **Examples**.
+#' @details Objects of class `"draws_rvars"` are lists of [`rvar`] objects. See **Examples**.
 #'
 NULL
 
@@ -164,21 +164,27 @@ as_draws_rvars.mcmc.list <- function(x, ...) {
 #' @rdname draws_rvars
 #' @export
 draws_rvars <- function(..., .nchains = 1) {
-  # TODO: should this be as_rvar or rvar? depends on desired constructor...
-  out <- lapply(list(...), as_rvar)
+  out <- lapply(list(...), function(x) {
+    if (is_rvar(x)) x
+    else rvar(x)
+  })
+
   if (!rlang::is_named(out)) {
     stop2("All variables must be named.")
   }
+
   .nchains <- as_one_integer(.nchains)
   if (.nchains < 1) {
     stop2("Number of chains must be positive.")
   }
+
   .ndraws <- ndraws(out[[1]])
   if (.ndraws %% .nchains != 0) {
     stop2("Number of chains does not divide the number of draws.")
   }
+
   # TODO: store nchains somewhere, maybe as an attribute
-  as_draws_rvars(out)
+  .as_draws_rvars(out)
 }
 
 class_draws_rvars <- function() {

R/rdo.R

@@ -2,27 +2,27 @@
 #'
 #' Execute an expression to create a random variable.
 #'
-#' @param expr A bare expression that can (optionally) contain [rvar]s. The expression
+#' @param expr A bare expression that can (optionally) contain [`rvar`]s. The expression
 #' supports [quasiquotation].
-#' @param ndraws When no [rvar]s are supplied in `expr`, this is the number
+#' @param ndraws When no [`rvar`]s are supplied in `expr`, this is the number
 #' of draws that will be used to construct new random variables. If `NULL`,
 #' getOption("rvar_ndraws") is used (default 4000).
 #' @template args-rvar-dim
 #'
 #' @details This function evaluates `expr` possibly multiple times, once for each draw of
-#' the [rvar]s it contains, then returns a new [rvar] representing the output of those
-#' expressions. To identify [rvar]s, `rdo()` searches the calling environment for any variables
-#' named in `expr` for which [is_rvar()] evaluates to `TRUE`. If `expr` contains no [rvar]s,
-#' then it will be executed `ndraws` times and an [rvar] with that many draws returned.
+#' the [`rvar`]s it contains, then returns a new [`rvar`] representing the output of those
+#' expressions. To identify [`rvar`]s, `rdo()` searches the calling environment for any variables
+#' named in `expr` for which [is_rvar()] evaluates to `TRUE`. If `expr` contains no [`rvar`]s,
+#' then it will be executed `ndraws` times and an [`rvar`] with that many draws returned.
 #'
 #' `rdo()` is not necessarily *fast* (in fact in some cases it may be very slow), but
-#' it has the advantage of allowing nearly arbitrary R code to be executed against [rvar]s
+#' it has the advantage of allowing nearly arbitrary R code to be executed against [`rvar`]s
 #' simply by wrapping it with `rdo( ... )`. This makes it especially useful as a prototyping
 #' tool. If you create code with `rdo()` and it is unacceptably slow for your application,
-#' consider rewriting it in terms of math operations directly on [rvar]s (which should be fast),
-#' or in terms of operations directly on the arrays that back the [rvar]s, using [draws_of()].
+#' consider rewriting it in terms of math operations directly on [`rvar`]s (which should be fast),
+#' or in terms of operations directly on the arrays that back the [`rvar`]s, using [draws_of()].
 #'
-#' @return An [rvar].
+#' @return An [`rvar`].
 #'
 #' @examples
 #'

R/rfun.R

@@ -4,18 +4,18 @@
 #'
 #' @param .f A function (or a one-sided formula representing a function that can be parsed by
 #' [rlang::as_function()]) to turn into a function that accepts and/or produces random variables.
-#' @param rvar_args The arguments of `.f` that should be allowed to accept [rvar]s as arguments.
+#' @param rvar_args The arguments of `.f` that should be allowed to accept [`rvar`]s as arguments.
 #' If `NULL` (the default), all arguments to `.f` are turned into arguments that accept
-#' [rvar]s.
-#' @param ndraws When no [rvar]s are supplied as arguments to the new function, this is the number
+#' [`rvar`]s.
+#' @param ndraws When no [`rvar`]s are supplied as arguments to the new function, this is the number
 #' of draws that will be used to construct new random variables. If `NULL`,
 #' `getOption("rvar_ndraws")` is used (default 4000).
 #'
-#' @details This function wraps an existing funtion (`.f`) such that it returns [rvar]s containing
+#' @details This function wraps an existing funtion (`.f`) such that it returns [`rvar`]s containing
 #' whatever type of data `.f` would normally return.
 #'
 #' @return A function with the same argument specification as `.f`, but which can accept and return
-#' [rvar]s.
+#' [`rvar`]s.
 #'
 #' @export
 rfun <- function (.f, rvar_args = NULL, ndraws = NULL) {

R/rvar-.R

@@ -5,7 +5,7 @@
 #' @name rvar
 #'
 #' @param x A vector or array where the first dimension represents draws from
-#' a distribution. The resulting [rvar] will have dimension `dim(x)[-1]`; that is,
+#' a distribution. The resulting [`rvar`] will have dimension `dim(x)[-1]`; that is,
 #' everything except the first dimension is used for the shape of the variable, and the
 #' first dimension is used to index draws from the distribution.
 #' @template args-rvar-dim
@@ -80,13 +80,13 @@ new_rvar <- function(x = double()) {
 
 #' Is `x` a random variables?
 #'
-#' Test if `x` is an [rvar()].
+#' Test if `x` is an [`rvar`].
 #'
 #' @param x An object
 #'
 #' @seealso [as_rvar()] to convert objects to `rvar`s.
 #'
-#' @return `TRUE` if `x` is an [rvar()], `FALSE` otherwise.
+#' @return `TRUE` if `x` is an [`rvar`], `FALSE` otherwise.
 #'
 #' @export
 is_rvar <- function(x) {
@@ -393,20 +393,20 @@ as.list.rvar <- function(x, ...) {
 
 #' Get/set array of draws underlying a random variable
 #'
-#' Gets/sets the array-representation that backs an [rvar()]. Should be used rarely.
+#' Gets/sets the array-representation that backs an [`rvar`]. Should be used rarely.
 #'
-#' @param x An [rvar()]
+#' @param x An [`rvar`]
 #' @param value An array
 #'
 #' @details
 #'
-#' While [rvar]s implement fast versions of basic math operations (including
+#' While [`rvar`]s implement fast versions of basic math operations (including
 #' [matrix multiplication][rvar-matmult]), sometimes you may need to bypass
-#' the [rvar] abstraction to do what you need to do more efficiently.
+#' the [`rvar`] abstraction to do what you need to do more efficiently.
 #' `draws_of()` allows you to get / set the underlying array of draws in
 #' order to do that.
 #'
-#' [rvar]s represent draws internally using arrays of arbitrary dimension, which
+#' [`rvar`]s represent draws internally using arrays of arbitrary dimension, which
 #' is returned by `draws_of(x)` and can be set using `draws_of(x) <- value`.
 #' The **first** dimension of these arrays is the index of the draws.
 #'
@@ -469,9 +469,9 @@ vec_restore.rvar <- function(x, ...) {
 #'
 #' The probability density function (`density()`), cumulative distribution
 #' function (`cdf()`), and quantile function / inverse CDF (`quantile()`) of
-#' an [rvar()].
+#' an [`rvar`].
 #'
-#' @param x an [rvar()]
+#' @param x an [`rvar`]
 #' @param q,at vector of quantiles.
 #' @param probs vector of probabilities
 #' @param ... Additional arguments passed onto underlying methods:
@@ -482,7 +482,7 @@ vec_restore.rvar <- function(x, ...) {
 #' @return
 #'
 #' A vector of the same length as the input (`q`, `at`, or `probs`) containing
-#' values from the corresponding function of the given [rvar()].
+#' values from the corresponding function of the given [`rvar`].
 #'
 #' @name rvar-functions
 #' @export
@@ -543,8 +543,7 @@ bind_rvar <- function(.f, args, .axis = 2) {
   }
 
   if (is.data.frame(args[[2]])) {
-    # TODO
-    stop2("not implemented")
+    stop2("TODO: IMPLEMENT")
   }
 
   args[[2]] <- as_rvar(args[[2]])

R/rvar-cast.R

@@ -1,20 +1,20 @@
 #' Coerce to a random variable
 #'
-#' Convert `x` to an [rvar()] object.
+#' Convert `x` to an [`rvar`] object.
 #'
-#' @param x An object that can be converted to an [rvar], such as a vector or array
-#' (or an [rvar] itself).
+#' @param x An object that can be converted to an [`rvar`], such as a vector or array
+#' (or an [`rvar`] itself).
 #' @template args-rvar-dim
 #'
-#' @details For objects that are already [rvar]s, returns them (with modified dimensions
+#' @details For objects that are already [`rvar`]s, returns them (with modified dimensions
 #' if `dim` is not `NULL`).
 #'
-#' For numeric or logical vectors or arrays, returns an [rvar] with a single draw and
+#' For numeric or logical vectors or arrays, returns an [`rvar`] with a single draw and
 #' the same dimensions as `x`. This is in contrast to the [rvar()] constructor, which
 #' treats the first dimension of `x` as the draws dimension. As a result, `as_rvar()`
 #' is useful for creating constants.
 #'
-#' @seealso [rvar()] to construct [rvar]s directly.
+#' @seealso [rvar()] to construct [`rvar`]s directly.
 #'
 #' @return An object of class `"rvar"` representing a random variable.
 #'
@@ -37,7 +37,7 @@ as_rvar <- function(x, dim = NULL) {
 
 #' rvar vctrs compatibility
 #'
-#' These functions implement compatibility with [vctrs-package] for [rvar]s.
+#' These functions implement compatibility with [vctrs-package] for [`rvar`]s.
 #'
 #' @name vctrs-compat
 #'

R/rvar-math.R

@@ -5,12 +5,12 @@
 #' Compute expectations (`E()` or `mean()`), probabilities (`Pr()`), and
 #' medians (`median()`) from a random variable.
 #'
-#' @param x an [rvar()]
+#' @param x an [`rvar`]
 #' @param na.rm Should `NA` values in the random variable be removed before
 #' computing summaries?
 #'
 #' Both `E()`, `mean()`, and `Pr()` take means over the draws dimension of the provided
-#' random variable. `Pr()` additionally checks that the provided [rvar]
+#' random variable. `Pr()` additionally checks that the provided [`rvar`]
 #' is a logical variable (hence, taking its expectation results in a probability).
 #' `median()` takes medians.
 #'
@@ -68,7 +68,7 @@ Pr <- function(x, na.rm = FALSE) {
 #'
 #' Compute summaries of random variables within draws, producing a new random variable.
 #'
-#' @param x an [rvar()]
+#' @param x an [`rvar`]
 #' @param na.rm Should `NA` values in the random variable be removed before
 #' computing summaries?
 #'
@@ -85,7 +85,7 @@ Pr <- function(x, na.rm = FALSE) {
 #' - `range()`
 #'
 #' @return
-#' An [rvar()] of length 1 (or in the case of `range()`, length 2) with the same number
+#' An [`rvar`] of length 1 (or in the case of `range()`, length 2) with the same number
 #' of draws as the input rvar(s) containing the summary statistic computed within
 #' each draw of the input rvar(s).
 #'
@@ -189,22 +189,22 @@ Math.rvar <- function(x, ...) {
 #'
 #' @name rvar-matmult
 #' @aliases %**%
-#' @param x An [rvar], [numeric], or [logical]. Must be 1 or 2-dimensional. If it is a vector,
+#' @param x An [`rvar`], [`numeric`], or [`logical`]. Must be 1 or 2-dimensional. If it is a vector,
 #' it is treated as a row vector.
-#' @param y An [rvar], [numeric], or [logical]. Must be 1 or 2-dimensional. If it is a vector,
+#' @param y An [`rvar`], [`numeric`], or [`logical`]. Must be 1 or 2-dimensional. If it is a vector,
 #' it is treated as a column vector.
 #'
 #' @details
 #' If `x` or `y` are vectors, they are converted into matrices prior to multiplication, with `x`
 #' converted to a row vector and `y` to a column vector. Numerics and logicals can be multiplied
-#' by [rvar]s and are broadcasted across all draws of the [rvar] argument. Tensor multiplication
-#' is used to efficiently multiply matrices across draws, so if either `x` or `y` is an [rvar],
+#' by [`rvar`]s and are broadcasted across all draws of the [`rvar`] argument. Tensor multiplication
+#' is used to efficiently multiply matrices across draws, so if either `x` or `y` is an [`rvar`],
 #' `x %**% y` will be much faster than `rdo(x %*% y)`.
 #'
-#' Because [rvar] is an S3 class and S3 classes cannot properly override `%*%`, [rvar]s use
+#' Because [`rvar`] is an S3 class and S3 classes cannot properly override `%*%`, [`rvar`]s use
 #' `%**%` for matrix multiplication.
 #'
-#' @return An [rvar] representing the matrix product of `x` and `y`.
+#' @return An [`rvar`] representing the matrix product of `x` and `y`.
 #'
 #' @importFrom tensorA mul.tensor as.tensor
 #' @export

R/rvar-print.R

@@ -1,9 +1,9 @@
 #' Print or format a random variable
 #'
-#' Printing and formatting methods for [rvar]s.
+#' Printing and formatting methods for [`rvar`]s.
 #'
 #' @encoding UTF-8
-#' @param x,object An [rvar].
+#' @param x,object An [`rvar`].
 #' @param color Whether or not to use color when formatting the output. If `TRUE`,
 #' the [pillar::style_num()] functions may be used to produce strings containing
 #' control sequences to produce colored output on the terminal.
@@ -16,10 +16,10 @@
 #' @param ... Further arguments passed to other functions.
 #'
 #' @details
-#' `print()` and `str()` print out [rvar()] objects by summarizing each element
+#' `print()` and `str()` print out [`rvar`] objects by summarizing each element
 #' in the random variable with either its mean±sd or median±mad, depending on
 #' the value of `summary`. Both functions use the `format()` implementation for
-#' [rvar()] objects under the hood, which returns a character vector in the
+#' [`rvar`] objects under the hood, which returns a character vector in the
 #' mean±sd or median±mad form.
 #'
 #' @return

man-roxygen/args-rvar-dim.R

@@ -1,2 +1,2 @@
-#' @param dim Override for the dimensions of the [rvar] to be created (see [dim()]): an integer vector of length one
+#' @param dim Override for the dimensions of the [`rvar`] to be created (see [dim()]): an integer vector of length one
 #' or more giving the maximal indices in each dimension. If `NULL` (the default), this is determined by the input.