1.4 Examples

The following examples make use of the demo package roxygenExPkg. The package can be installed as:

remotes::install_github(
  "miraisolutions/techguides/roxygen-guidelines/roxygenExPkg"
)

The command help(package = "roxygenExPkg") will give you access to the package help.

1.4.1 General content organization

See the corresponding ?roxygenExPkg::fun_doc.

#' Function Documentation Example
#'
#' Show an example of roxygen tags organization, providing documentation best
#' practices and guidelines. An explicit `@description` is only needed for
#' multi-paragraph descriptions.
#'
#' @param first_arg Description of the first argument. Also define data type /
#'   class / structure / vectorization expectations where not obvious, and
#'   possibly use (see 'Details').
#' @param second_arg Second argument of the function.
#'
#' @details More details or context about the function and its behaviour. List
#'   possible side-effects, corner-cases and limitations here. Also use this
#'   section for describing the meaning and usage of arguments when this is too
#'   complex or verbose for the `@param` tags.
#'
#' @section Custom section:
#' The content of a custom section.
#'
#' @return Returns `NULL`, invisibly. The function is called for illustration
#'   purposes only.
#'
#' @references
#' Hadley Wickham, Peter Danenberg and Manuel Eugster. roxygen2: In-Line
#' Documentation for R. [https://CRAN.R-project.org/package=roxygen2]().
#'
#' Hadley Wickham, The tidyverse style guide.
#' [http://style.tidyverse.org/documentation.html]().
#'
#' @seealso [fun_doc_tpl()], [roxygen2::roxygenize()]. Even if you just put
#'   comma-separated links to functions, don't forget the final period (.).
#' @family function documentation examples
#'
#' @examples
#' # illustrate through examples how functions can be used
#' fun_doc("example_string", 3)
#'
#' @importFrom roxygen2 roxygenize
#' @importFrom roxygen2 roxygenise
#' @export
#'
#' @md
fun_doc <- function(first_arg, second_arg) {
  invisible()
}

1.4.2 Templates and example scripts

See the corresponding ?roxygenExPkg::fun_doc_tpl.

#' Template Documentation Example
#'
#' Show an example of roxygen tags organization, providing documentation best
#' practices and guidelines, using templates.
#'
#' @template param-first_arg
#' @param second_arg Description of the second argument.
#'
#' @template details-fun_doc
#'
#' @section Custom section:
#' The content of a custom section.
#'
#' @template return-NULL
#'
#' @template reference-roxygen2
#' @template reference-tidyverse_style_guide
#'
#' @seealso [fun_doc_tpl()], [roxygen2::roxygenize()]. Even if you just put
#'   comma-separated links to functions, don't forget the final period (.).
#' @family function documentation examples
#'
#' @example man-roxygen/ex-fun_doc_tpl.R
#'
#' @importFrom roxygen2 roxygenize
#' @importFrom roxygen2 roxygenise
#' @export
#'
#' @md
fun_doc_tpl <- function(first_arg, second_arg) {
  invisible()
}

1.4.3 @rdname

See the corresponding ?roxygenExPkg::divide.

#' Scalar Division
#'
#' Divide an object by a scalar.
#'
#' @param x The object to be divided
#' @param d Scalar to divide `x` by.
#'
#' @return The result of the scalar division of `x`.
#'
#' @examples
#' x <- matrix(1:6, 3L)
#'
#' @name divide
#'
#' @md
NULL

#' @rdname divide
#'
#' @details `divide_by()` performes generic division by `d`.
#'
#' @examples
#' divide_by(x, 1.5)
#'
#' @export
#'
#' @md
divide_by <- function(x, d) {
  x / d
}

#' @rdname divide
#'
#' @details `divide_by2()` performes division by two.
#'
#' @examples
#' divide_by2(x)
#'
#' @export
#'
#' @md
divide_by2 <- function(x) {
  divide_by(x, 2)
}

#' @rdname divide
#'
#' @details `divide_by3()` performes division by three.
#'
#' @examples
#' divide_by3(x)
#'
#' @export
#'
#' @md
divide_by3 <- function(x) {
  divide_by(x, 3)
}

#' @rdname divide
#'
#' @details `divide_by4()` performes division by four.
#'
#' @examples
#' divide_by4(x)
#'
#' @export
#'
#' @md
divide_by4 <- function(x) {
  divide_by(x, 4)
}

1.4.4 @describeIn

See the corresponding ?roxygenExPkg::times.

#' Scalar Multiplication
#'
#' Multiply an object by a scalar.
#'
#' @param x The object to be multiplied.
#' @param m Scalar to multiply `x` by.
#'
#' @return The result of the scalar multiplication of `x`.
#'
#' @describeIn times Generic multiplication by `m`.
#'
#' @examples
#' x <- matrix(1:6, 3L)
#'
#' times(x, 1.5)
#'
#' @export
#'
#' @md
times <- function(x, m) {
  x * m
}

#' @describeIn times Multiplication by 2.
#'
#' @examples
#' times2(x)
#'
#' @export
#'
#' @md
times2 <- function(x) {
  times(x, 2)
}

#' @describeIn times Multiplication by 3.
#'
#' @examples
#' times3(x)
#'
#' @export
#'
#' @md
times3 <- function(x) {
  times(x, 3)
}

#' @describeIn times Multiplication by 4.
#'
#' @examples
#' times4(x)
#'
#' @export
#'
#' @md
times4 <- function(x) {
  times(x, 4)
}