Improve sentence style in @param documentation

DESCRIPTION

@@ -203,3 +203,4 @@ Collate:
     'utils-vignettes.R'
     'zzz.R'
 Config/roxygen2/version: 8.1.0
+Roxygen: list(markdown = TRUE)

R/block.R

@@ -180,17 +180,17 @@ block_exec = function(options) {
 #' Engine for R
 #'
 #' This function handles the execution of R code blocks (when the chunk option
-#' \code{engine} is \code{'R'}) and generates the R output for each code block.
+#' `engine` is `'R'`) and generates the R output for each code block.
 #'
-#' This engine function has one argument \code{options}: the source code of the
-#' current chunk is in \code{options$code}. It returns a processed output that
+#' This engine function has one argument `options`: the source code of the
+#' current chunk is in `options$code`. It returns a processed output that
 #' can consist of data frames (as tables), graphs, or character output. This
 #' function is intended for advanced use to allow developers to extend R, and
 #' customize the pipeline with which R code is executed and processed within
 #' knitr.
 #'
 #' @param options A list of chunk options. Usually this is just the object
-#'   \code{options} associated with the current code chunk.
+#'   `options` associated with the current code chunk.
 #' @noRd
 eng_r = function(options) {
   # eval chunks (in an empty envir if cache)

R/cache.R

@@ -127,25 +127,25 @@ cache_rx = '_[abcdef0123456789]{32}[.](rdb|rdx|RData)$'
 
 #' Build automatic dependencies among chunks
 #'
-#' When the chunk option \code{autodep = TRUE}, all names of objects created in
+#' When the chunk option `autodep = TRUE`, all names of objects created in
 #' a chunk will be saved in a file named \file{__objects} and all global objects
 #' used in a chunk will be saved to \file{__globals}. This function can analyze
 #' object names in these files to automatically build cache dependencies, which
-#' is similar to the effect of the \code{dependson} option. It is supposed to be
+#' is similar to the effect of the `dependson` option. It is supposed to be
 #' used in the first chunk of a document and this chunk must not be cached.
 #' @param path Path to the dependency file.
 #' @param labels A vector of labels of chunks for which the dependencies will be
 #'   built. By default, dependencies for all chunks will be built.
-#' @return \code{NULL}. The dependencies are built as a side effect.
-#' @note Be cautious about \code{path}: because this function is used in a
+#' @return `NULL`. The dependencies are built as a side effect.
+#' @note Be cautious about `path`: because this function is used in a
 #'   chunk, the working directory when the chunk is evaluated is the directory
-#'   of the input document in \code{\link{knit}}, and if that directory differs
-#'   from the working directory before calling \code{knit()}, you need to adjust
-#'   the \code{path} argument here to make sure this function can find the cache
+#'   of the input document in [knit()], and if that directory differs
+#'   from the working directory before calling `knit()`, you need to adjust
+#'   the `path` argument here to make sure this function can find the cache
 #'   files \file{__objects} and \file{__globals}.
 #' @export
-#' @seealso \code{\link{dep_prev}}
-#' @references \url{https://yihui.org/knitr/demo/cache/}
+#' @seealso [dep_prev()]
+#' @references <https://yihui.org/knitr/demo/cache/>
 dep_auto = function(path = opts_chunk$get('cache.path'), labels = all_labels()) {
   # this function should be evaluated in the original working directory
   owd = setwd(opts_knit$get('output.dir')); on.exit(setwd(owd))
@@ -179,7 +179,7 @@ parse_objects = function(path) {
 
 #' Load the cache database of a code chunk
 #'
-#' If a code chunk has turned on the chunk option \code{cache = TRUE}, a cache
+#' If a code chunk has turned on the chunk option `cache = TRUE`, a cache
 #' database will be established after the document is compiled. You can use this
 #' function to manually load the database anywhere in the document (even before
 #' the code chunk). This makes it possible to use objects created later in the
@@ -189,28 +189,28 @@ parse_objects = function(path) {
 #' they are created.
 #' @param label The chunk label of the code chunk that has a cache database.
 #' @param object The name of the object to be fetched from the database. If it
-#'   is missing, \code{NULL} is returned).
-#' @param notfound A value to use when the \code{object} cannot be found.
+#'   is missing, `NULL` is returned).
+#' @param notfound A value to use when the `object` cannot be found.
 #' @param path Path of the cache database (normally set in the global chunk
-#'   option \code{cache.path}).
+#'   option `cache.path`).
 #' @param dir Path to use as the working directory. Defaults to the output
 #'   directory if run inside a \pkg{knitr} context and to the current working
-#'   directory otherwise. Any relative \code{path} is defined from \code{dir}.
+#'   directory otherwise. Any relative `path` is defined from `dir`.
 #' @param envir Environment to use for cache loading, into which all objects in
-#'   the cache for the specified chunk (not just that in \code{object}) will be
-#'   loaded. Defaults to the value in \code{\link{knit_global}}.
-#' @param lazy Whether to \code{\link{lazyLoad}} the cache database (depending
-#'   on the chunk option \code{cache.lazy = TRUE} or \code{FALSE} of that code
+#'   the cache for the specified chunk (not just that in `object`) will be
+#'   loaded. Defaults to the value in [knit_global()].
+#' @param lazy Whether to [lazyLoad()] the cache database (depending
+#'   on the chunk option `cache.lazy = TRUE` or `FALSE` of that code
 #'   chunk).
 #' @note Apparently this function loads the value of the object from the
-#'   \emph{previous} run of the document, which may be problematic when the
+#'   *previous* run of the document, which may be problematic when the
 #'   value of the object becomes different the next time the document is
 #'   compiled. Normally you must compile the document twice to make sure the
 #'   cache database is created, and the object can be read from it. Please use
 #'   this function with caution.
 #' @references See the example #114 at
-#'   \url{https://github.com/yihui/knitr-examples}.
-#' @return Invisible \code{NULL} when \code{object} is not specified (the cache
+#'   <https://github.com/yihui/knitr-examples>.
+#' @return Invisible `NULL` when `object` is not specified (the cache
 #'   database will be loaded as a side effect), otherwise the value of the
 #'   object if found.
 #' @export
@@ -250,11 +250,11 @@ load_cache = function(
 #' This function can be used to build dependencies among chunks so that all
 #' later chunks depend on previous chunks, i.e. whenever the cache of a previous
 #' chunk is updated, the cache of all its later chunks will be updated.
-#' @return \code{NULL}; the internal dependency structure is updated as a side
+#' @return `NULL`; the internal dependency structure is updated as a side
 #'   effect.
 #' @export
-#' @seealso \code{\link{dep_auto}}
-#' @references \url{https://yihui.org/knitr/demo/cache/}
+#' @seealso [dep_auto()]
+#' @references <https://yihui.org/knitr/demo/cache/>
 dep_prev = function() {
   labs = names(knit_code$get())
   if ((n <- length(labs)) < 2L) return() # one chunk or less; no sense of deps
@@ -266,15 +266,15 @@ dep_prev = function() {
 
 #' An unevaluated expression to return .Random.seed if exists
 #'
-#' This expression returns \code{.Random.seed} when \code{eval(rand_seed)} and
-#' \code{NULL} otherwise.
+#' This expression returns `.Random.seed` when `eval(rand_seed)` and
+#' `NULL` otherwise.
 #'
-#' It is designed to work with \code{opts_chunk$set(cache.extra = rand_seed)}
+#' It is designed to work with `opts_chunk$set(cache.extra = rand_seed)`
 #' for reproducibility of chunks that involve with random number generation. See
 #' references.
 #' @export
 #' @format NULL
-#' @references \url{https://yihui.org/knitr/demo/cache/}
+#' @references <https://yihui.org/knitr/demo/cache/>
 #' @examples eval(rand_seed)
 #' rnorm(1) # .Random.seed is created (or modified)
 #' eval(rand_seed)
@@ -288,12 +288,12 @@ rand_seed = quote({
 #' will not be automatically cleaned. You can use this function to identify
 #' these possible files, and clean them if you are sure they are no longer
 #' needed.
-#' @param clean Boolean; whether to remove the files.
+#' @param clean Whether to remove the files.
 #' @param path Path to the cache.
 #' @note  The identification is not guaranteed to be correct, especially when
 #'   multiple documents share the same cache directory. You are recommended to
-#'   call \code{clean_cache(FALSE)} and carefully check the list of files (if
-#'   any) before you really delete them (\code{clean_cache(TRUE)}).
+#'   call `clean_cache(FALSE)` and carefully check the list of files (if
+#'   any) before you really delete them (`clean_cache(TRUE)`).
 #'
 #'   This function must be called within a code chunk in a source document,
 #'   since it needs to know all chunk labels of the current document to

R/citation.R

@@ -1,7 +1,7 @@
 #' Generate BibTeX bibliography databases for R packages
 #'
-#' A wrapper function of \code{xfun::pkg_bib()}.
-#' @param ...,prefix Arguments passed to \code{xfun::\link[xfun]{pkg_bib}()}.
+#' A wrapper function of `xfun::pkg_bib()`.
+#' @param ...,prefix Arguments passed to [xfun::pkg_bib()].
 #' @export
 write_bib = function(..., prefix = getOption('knitr.bib.prefix', 'R-')) {
   xfun::pkg_bib(..., prefix = prefix)

R/defaults.R

@@ -57,26 +57,26 @@ new_defaults = function(value = list()) {
 
 #' Default and current chunk options
 #'
-#' Options for R code chunks. When running R code, the object \code{opts_chunk}
+#' Options for R code chunks. When running R code, the object `opts_chunk`
 #' (default options) is not modified by chunk headers (local chunk options are
-#' merged with default options), whereas \code{opts_current} (current options)
+#' merged with default options), whereas `opts_current` (current options)
 #' changes with different chunk headers and it always reflects the options for
 #' the current chunk.
 #'
 #' Normally we set up the global options once in the first code chunk in a
-#' document using \code{opts_chunk$set()}, so that all \emph{latter} chunks will
+#' document using `opts_chunk$set()`, so that all *latter* chunks will
 #' use these options. Note the global options set in one chunk will not affect
 #' the options in this chunk itself, and that is why we often need to set global
 #' options in a separate chunk.
 #'
-#' See \code{str(knitr::opts_chunk$get())} for a list of default chunk options.
-#' @references Usage: \url{https://yihui.org/knitr/objects/}
+#' See `str(knitr::opts_chunk$get())` for a list of default chunk options.
+#' @references Usage: <https://yihui.org/knitr/objects/>
 #'
 #'   A list of available options:
-#'   \url{https://yihui.org/knitr/options/#chunk-options}
-#' @note \code{opts_current} should be treated as read-only and you are supposed
-#'   to only query its values via \code{opts_current$get()}. Calling
-#'   \code{opts_current$set()} will throw an error.
+#'   <https://yihui.org/knitr/options/#chunk-options>
+#' @note `opts_current` should be treated as read-only and you are supposed
+#'   to only query its values via `opts_current$get()`. Calling
+#'   `opts_current$set()` will throw an error.
 #' @export
 #' @examples opts_chunk$get('prompt'); opts_chunk$get('fig.keep')
 opts_chunk = new_defaults(list(
@@ -164,7 +164,7 @@ opts_chunk_attr = local({
 #' aliases and the elements in this vector are the real option names.
 #' @param ... Named arguments. Argument names are aliases, and argument values
 #'   are real option names.
-#' @return \code{NULL}. \code{opts_knit$get('aliases')} is modified as the side effect.
+#' @return `NULL`. `opts_knit$get('aliases')` is modified as the side effect.
 #' @export
 #' @examples set_alias(w = 'fig.width', h = 'fig.height')
 #' # then we can use options w and h in chunk headers instead of fig.width and fig.height
@@ -177,19 +177,19 @@ set_alias = function(...) {
 #' Options including whether to use a progress bar when knitting a document, and
 #' the base directory of images, etc.
 #'
-#' Besides the standard usage (\code{opts_knit$set()}), we can also set package
-#' options prior to loading \code{knitr} or calling \code{knit()} using
-#' \code{\link{options}()} in base R. A global option \code{knitr.package.foo}
-#' in \code{options()} will be set as an option \code{foo} in \code{opts_knit},
-#' i.e. global options in base R with the prefix \code{knitr.package.}
-#' correspond to options in \code{opts_knit}. This can be useful to set package
+#' Besides the standard usage (`opts_knit$set()`), we can also set package
+#' options prior to loading `knitr` or calling `knit()` using
+#' [options()] in base R. A global option `knitr.package.foo`
+#' in `options()` will be set as an option `foo` in `opts_knit`,
+#' i.e. global options in base R with the prefix `knitr.package.`
+#' correspond to options in `opts_knit`. This can be useful to set package
 #' options in \file{~/.Rprofile} without loading \pkg{knitr}.
 #'
-#' See \code{str(knitr::opts_knit$get())} for a list of default package options.
-#' @references Usage: \url{https://yihui.org/knitr/objects/}
+#' See `str(knitr::opts_knit$get())` for a list of default package options.
+#' @references Usage: <https://yihui.org/knitr/objects/>
 #'
 #'   A list of available options:
-#'   \url{https://yihui.org/knitr/options/#package-options}
+#'   <https://yihui.org/knitr/options/#package-options>
 #' @export
 #' @examples opts_knit$get('verbose'); opts_knit$set(verbose = TRUE)  # change it
 #' if (interactive()) {

R/engine.R

@@ -1,32 +1,32 @@
 #' Engines of other languages
 #'
 #' This object controls how to execute the code from languages other than R
-#' (when the chunk option \code{engine} is not \code{'R'}). Each component in
+#' (when the chunk option `engine` is not `'R'`). Each component in
 #' this object is a function that takes a list of current chunk options
 #' (including the source code) and returns a character string to be written into
 #' the output.
 #'
-#' The engine function has one argument \code{options}: the source code of the
-#' current chunk is in \code{options$code}. Usually we can call external
-#' programs to run the code via \code{\link{system2}}. Other chunk options are
-#' also contained in this argument, e.g. \code{options$echo} and
-#' \code{options$eval}, etc.
+#' The engine function has one argument `options`: the source code of the
+#' current chunk is in `options$code`. Usually we can call external
+#' programs to run the code via [system2()]. Other chunk options are
+#' also contained in this argument, e.g. `options$echo` and
+#' `options$eval`, etc.
 #'
-#' In most cases, \code{options$engine} can be directly used in command line to
-#' execute the code, e.g. \code{python} or \code{ruby}, but sometimes we may
+#' In most cases, `options$engine` can be directly used in command line to
+#' execute the code, e.g. `python` or `ruby`, but sometimes we may
 #' want to specify the path of the engine program, in which case we can pass it
-#' through the \code{engine.path} option. For example, \code{engine='ruby',
-#' engine.path='/usr/bin/ruby1.9.1'}. Additional command line arguments can be
-#' passed through \code{options$engine.opts}, e.g. \code{engine='ruby',
-#' engine.opts='-v'}.
+#' through the `engine.path` option. For example, `engine='ruby',
+#' engine.path='/usr/bin/ruby1.9.1'`. Additional command line arguments can be
+#' passed through `options$engine.opts`, e.g. `engine='ruby',
+#' engine.opts='-v'`.
 #'
-#' See \code{str(knitr::knit_engines$get())} for a list of built-in language
+#' See `str(knitr::knit_engines$get())` for a list of built-in language
 #' engines.
 #' @export
-#' @note The Leiningen engine \code{lein} requires lein-exec plugin; see
-#'   \url{https://github.com/yihui/knitr/issues/1176} for details.
-#' @references Usage: \url{https://yihui.org/knitr/objects/}; examples:
-#'   \url{https://yihui.org/knitr/demo/engines/}
+#' @note The Leiningen engine `lein` requires lein-exec plugin; see
+#'   <https://github.com/yihui/knitr/issues/1176> for details.
+#' @references Usage: <https://yihui.org/knitr/objects/>; examples:
+#'   <https://yihui.org/knitr/demo/engines/>
 #' @examples knit_engines$get('python'); knit_engines$get('awk')
 #' names(knit_engines$get())
 knit_engines = new_defaults()
@@ -35,18 +35,18 @@ knit_engines = new_defaults()
 #' Cache engines of other languages
 #'
 #' This object controls how to load cached environments from languages other
-#' than R (when the chunk option \code{engine} is not \code{'R'}). Each
+#' than R (when the chunk option `engine` is not `'R'`). Each
 #' component in this object is a function that takes the current path to the
 #' chunk cache and loads it into the language environment.
 #'
-#' The cache engine function has one argument \code{options}, a list containing
-#' all chunk options. Note that \code{options$hash} is the path to the current
+#' The cache engine function has one argument `options`, a list containing
+#' all chunk options. Note that `options$hash` is the path to the current
 #' chunk cache with the chunk's hash, but without any file extension, and the
 #' language engine may write a cache database to this path (with an extension).
 #'
 #' The cache engine function should load the cache environment and should know
 #' the extension appropriate for the language.
-#' @references See \url{https://github.com/rstudio/reticulate/pull/167} for an
+#' @references See <https://github.com/rstudio/reticulate/pull/167> for an
 #'   implementation of a cache engine for Python.
 #' @export
 cache_engines = new_defaults()
@@ -57,17 +57,17 @@ cache_engines = new_defaults()
 #' to format and return the text output from your engine.
 #'
 #' For expert users, an advanced usage of this function is
-#' \code{engine_output(options, out = LIST)} where \code{LIST} is a list that
-#' has the same structure as the output of \code{evaluate::evaluate()}. In this
-#' case, the arguments \code{code} and \code{extra} are ignored, and the list is
-#' passed to \code{knitr::sew()} to return a character vector of final output.
+#' `engine_output(options, out = LIST)` where `LIST` is a list that
+#' has the same structure as the output of `evaluate::evaluate()`. In this
+#' case, the arguments `code` and `extra` are ignored, and the list is
+#' passed to `knitr::sew()` to return a character vector of final output.
 #' @param options A list of chunk options. Usually this is just the object
-#'   \code{options} passed to the engine function; see
-#'   \code{\link{knit_engines}}.
-#' @param code Source code of the chunk, to which the output hook \code{source}
-#'   is applied, unless the chunk option \code{echo} is \code{FALSE}.
-#' @param out Text output from the engine, to which the hook \code{output} is
-#'   applied, unless the chunk option \code{results} is \code{'hide'}
+#'   `options` passed to the engine function; see
+#'   [knit_engines()].
+#' @param code Source code of the chunk, to which the output hook `source`
+#'   is applied, unless the chunk option `echo` is `FALSE`.
+#' @param out Text output from the engine, to which the hook `output` is
+#'   applied, unless the chunk option `results` is `'hide'`
 #' @param extra Any additional text output that you want to include.
 #' @return A character string generated from the source code and output using
 #'   the appropriate output hooks.