Improve roxygen2 usage

Rely on various modern roxygen2 features to simplify and streamline documentation and reduce duplications. There were also a bunch of documentation errors/mistakes that this PR fixes as well as various spelling harmonizations.

Note that unfortunately we can't use `@inheritParams` [since](r-lib/roxygen2#836 (comment))

> roxygen2 doesn't parse the usage block, so it doesn't know what the usage is, and hence it doesn't find any parameters to inherit.

Instead we use `@eval` to minimize duplication, cf. https://roxygen2.r-lib.org/articles/rd.html#evaluating-arbitrary-code

Also note that Markdown support in roxygen2 documentation tags is now enabled globally for the whole package which means percentage signs mustn't be escaped anymore.

DESCRIPTION

@@ -23,7 +23,9 @@ SystemRequirements: C++11
 Imports: 
     Rcpp, RApiSerialize, stringfish (>= 0.15.1)
 LinkingTo: Rcpp, RApiSerialize, stringfish
-RoxygenNote: 7.1.1
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.1.2
 Suggests: knitr, rmarkdown, testthat, dplyr, data.table
 VignetteBuilder: knitr
 Copyright: This package includes code from the 'zstd' library owned by Facebook, Inc. and created by Yann Collet; the 'lz4' library created and owned by Yann Collet; xxHash library created and owned by Yann Collet; and code derived from the 'Blosc' library created and owned by Francesc Alted.  

R/ascii_encoding.r

@@ -1,42 +1,43 @@
 #' Z85 Encoding
-#' 
+#'
 #' Encodes binary data (a raw vector) as ascii text using Z85 encoding format
 #' @usage base85_encode(rawdata)
 #' @param rawdata A raw vector
-#' @return A string representation of the raw vector. 
-#' @details 
+#' @return A string representation of the raw vector.
+#' @details
 #' Z85 is a binary to ascii encoding format created by Pieter Hintjens in 2010 and is part of the ZeroMQ RFC.
 #' The encoding has a dictionary using 85 out of 94 printable ASCII characters.
 #' There are other base 85 encoding schemes, including Ascii85, which is popularized and used by Adobe.
 #' Z85 is distinguished by its choice of dictionary, which is suitable for easier inclusion into source code for many programming languages.
 #' The dictionary excludes all quote marks and other control characters, and requires no special treatment in R and most other languages.
 #' Note: although the official specification restricts input length to multiples of four bytes, the implementation here works with any input length.
-#' The overhead (extra bytes used relative to binary) is 25\%. In comparison, base 64 encoding has an overhead of 33.33\%.
+#' The overhead (extra bytes used relative to binary) is 25%. In comparison, base 64 encoding has an overhead of 33.33%.
 
 #' @references https://rfc.zeromq.org/spec/32/
 #' @name base85_encode
 NULL
 
 #' Z85 Decoding
-#' 
+#'
 #' Decodes a Z85 encoded string back to binary
 #' @usage base85_decode(encoded_string)
 #' @param encoded_string A string
-#' @return The original raw vector. 
+#' @return The original raw vector.
 #' @name base85_decode
 NULL
 
 #' basE91 Encoding
-#' 
+#'
 #' Encodes binary data (a raw vector) as ascii text using basE91 encoding format
 #' @usage base91_encode(rawdata, quote_character = "\"")
 #' @param rawdata A raw vector
-#' @param quote_character The character to use in the encoding, replacing the double quote character. Must be a single quote "'", double quote "\"" or dash "-". 
-#' @return A string representation of the raw vector. 
-#' @details 
+#' @param quote_character The character to use in the encoding, replacing the double quote character. Must be either a single quote (`"'"`), a double quote
+#'   (`"\""`) or a dash (`"-"`).
+#' @return A string representation of the raw vector.
+#' @details
 #' basE91 (capital E for stylization) is a binary to ascii encoding format created by Joachim Henke in 2005.
-#' The overhead (extra bytes used relative to binary) is 22.97\% on average. In comparison, base 64 encoding has an overhead of 33.33\%.
-#' The original encoding uses a dictionary of 91 out of 94 printable ASCII characters excluding - (dash), \ (backslash) and ' (single quote).
+#' The overhead (extra bytes used relative to binary) is 22.97% on average. In comparison, base 64 encoding has an overhead of 33.33%.
+#' The original encoding uses a dictionary of 91 out of 94 printable ASCII characters excluding `-` (dash), `\` (backslash) and `'` (single quote).
 #' The original encoding does include double quote characters, which are less than ideal for strings in R. Therefore,
 #' you can use the `quote_character` parameter to substitute dash or single quote.
 #' @references http://base91.sourceforge.net/
@@ -49,11 +50,11 @@ base91_encode <- function(rawdata, quote_character = "\"") {
 }
 
 #' basE91 Decoding
-#' 
+#'
 #' Decodes a basE91 encoded string back to binary
 #' @usage base91_decode(encoded_string)
 #' @param encoded_string A string
-#' @return The original raw vector. 
+#' @return The original raw vector.
 base91_decode <- function(encoded_string) {
   stopifnot(length(encoded_string) == 1)
   has_double_quote <- grepl("\"", encoded_string)
@@ -68,13 +69,13 @@ base91_decode <- function(encoded_string) {
 }
 
 #' Encode and compress a file or string
-#' 
-#' A helper function for encoding and compressing a file or string to ascii using `base91_encode` and `qserialize` with the highest compression level. 
+#'
+#' A helper function for encoding and compressing a file or string to ascii using [base91_encode()] and [qserialize()] with the highest compression level.
 #' @usage encode_source(file = NULL, string = NULL, width = 120)
 #' @param file The file to encode (if `string` is not NULL)
 #' @param string The string to encode (if `file` is not NULL)
-#' @param width The output will be broken up into individual strings, with `width` being the longest allowable string. 
-#' @return A CharacterVector in base91 representing the compressed original file or string. 
+#' @param width The output will be broken up into individual strings, with `width` being the longest allowable string.
+#' @return A CharacterVector in base91 representing the compressed original file or string.
 encode_source <- function(file = NULL, string = NULL, width = 120) {
   if(!is.null(file)) {
     n <- file.info(file)$size
@@ -94,14 +95,13 @@ encode_source <- function(file = NULL, string = NULL, width = 120) {
 }
 
 #' Decode a compressed string
-#' 
-#' A helper function for encoding and compressing a file or string to ascii using `base91_encode` and `qserialize` with the highest compression level. 
+#'
+#' A helper function for encoding and compressing a file or string to ascii using [base91_encode()] and [qserialize()] with the highest compression level.
 #' @usage decode_source(string)
 #' @param string The string to decode
-#' @return The original (decoded) string. 
+#' @return The original (decoded) string.
 decode_source <- function(string) {
   x <- paste0(string, collapse = "")
   x <- base91_decode(x)
   qdeserialize(x)
 }
-

R/qcache.R

@@ -1,8 +1,8 @@
 #' qcache
-#' 
+#'
 #' Helper function for caching objects for long running tasks
-#' @usage qcache(expr, name, envir=parent.frame(), cache_dir=".cache", 
-#'               clear=FALSE, prompt=TRUE, qsave_params=list(), 
+#' @usage qcache(expr, name, envir=parent.frame(), cache_dir=".cache",
+#'               clear=FALSE, prompt=TRUE, qsave_params=list(),
 #'               qread_params=list())
 #' @param expr The expression to evaluate
 #' @param name The cached expression name (see details)
@@ -12,31 +12,31 @@
 #' @param prompt Whether to prompt before clearing
 #' @param qsave_params Parameters passed to `qsave`
 #' @param qread_params Parameters passed to `qread`
-#' @details 
-#' This is a (very) simple helper function to cache results of long running calculations. There are other packages specializing 
-#' in caching data that are more feature complete. 
-#' 
-#' The evaluated expression is saved with `qsave` in <cache_dir>/<name>.qs. 
-#' If the file already exists instead the expression is not evaluated and the cached result is read using `qread` and returned. 
-#' 
-#' To clear a cached result, you can manually delete the associated `qs` file, or you can call `qcache` with `clear=TRUE`. 
-#' If `prompt` is also `TRUE` a prompt will be given asking you to confirm deletion. 
-#' If `name` is not specified, all cached results in `cache_dir` will be removed. 
-#' @examples 
+#' @details
+#' This is a (very) simple helper function to cache results of long running calculations. There are other packages specializing
+#' in caching data that are more feature complete.
+#'
+#' The evaluated expression is saved with [qsave()] in `<cache_dir>/<name>.qs`.
+#' If the file already exists instead, the expression is not evaluated and the cached result is read using [qread()] and returned.
+#'
+#' To clear a cached result, you can manually delete the associated `.qs` file, or you can call [qcache()] with `clear=TRUE`.
+#' If `prompt` is also `TRUE` a prompt will be given asking you to confirm deletion.
+#' If `name` is not specified, all cached results in `cache_dir` will be removed.
+#' @examples
 #' cache_dir <- tempdir()
-#' 
+#'
 #' a <- 1
 #' b <- 5
-#' 
+#'
 #' # not cached
-#' result <- qcache({a + b}, 
-#'                  name="aplusb", 
+#' result <- qcache({a + b},
+#'                  name="aplusb",
 #'                  cache_dir = cache_dir,
 #'                  qsave_params = list(preset="fast"))
-#' 
+#'
 #' # cached
-#' result <- qcache({a + b}, 
-#'                  name="aplusb", 
+#' result <- qcache({a + b},
+#'                  name="aplusb",
 #'                  cache_dir = cache_dir,
 #'                  qsave_params = list(preset="fast"))
 #'