use roxygen2 md

shikokuchuo · Jan 15, 2025 · 6a5a217 · 6a5a217
1 parent 8d419ea
commit 6a5a217
Show file tree

Hide file tree

Showing 12 changed files with 91 additions and 100 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -24,4 +24,5 @@ Encoding: UTF-8
 Depends: 
     R (>= 3.5)
 RoxygenNote: 7.3.2
+Roxygen: list(markdown = TRUE)
 Config/build/compilation-database: true
diff --git a/R/base.R b/R/base.R
@@ -1,4 +1,4 @@
-# Copyright (C) 2024 Hibiki AI Limited <[email protected]>
+# Copyright (C) 2024-2025 Hibiki AI Limited <[email protected]>
 #
 # This file is part of secretbase.
 #
@@ -20,23 +20,23 @@
 #'
 #' Encodes a character string, raw vector or other object to base64 encoding.
 #' 
-#' A character string or raw vector (with no attributes) is encoded
-#' \emph{as is}, whilst all other objects are first serialized (using R
-#' serialisation version 3, big-endian representation).
+#' A character string or raw vector (with no attributes) is encoded *as is*,
+#' whilst all other objects are first serialized (using R serialisation version
+#' 3, big-endian representation).
 #'
 #' @param x an object.
-#' @param convert [default TRUE] logical TRUE to encode to a character string or
-#'   FALSE to a raw vector.
+#' @param convert logical TRUE to encode to a character string or FALSE to a raw
+#'   vector.
 #'
 #' @return A character string or raw vector depending on the value of
 #'   \sQuote{convert}.
 #'   
 #' @references
 #' This implementation is based that by 'The Mbed TLS Contributors' under the
 #' 'Mbed TLS' Trusted Firmware Project at
-#' \url{https://www.trustedfirmware.org/projects/mbed-tls}.
+#' <https://www.trustedfirmware.org/projects/mbed-tls>.
 #'     
-#' @seealso \code{\link{base64dec}}
+#' @seealso [base64dec()]
 #'
 #' @examples
 #' base64enc("secret base")
@@ -56,9 +56,9 @@ base64enc <- function(x, convert = TRUE) .Call(secretbase_base64enc, x, convert)
 #' objects), in order to return the original object.
 #'
 #' @param x an object.
-#' @param convert [default TRUE] logical TRUE to convert back to a character
-#'   string, FALSE to convert back to a raw vector or NA to decode and then
-#'   unserialize back to the original object.
+#' @param convert logical TRUE to convert back to a character string, FALSE to
+#'   convert back to a raw vector or NA to decode and then unserialize back to
+#'   the original object.
 #'
 #' @return A character string, raw vector, or other object depending on the
 #'   value of \sQuote{convert}. If conversion to a character string fails, a raw
@@ -67,9 +67,9 @@ base64enc <- function(x, convert = TRUE) .Call(secretbase_base64enc, x, convert)
 #' @references
 #' This implementation is based that by 'The Mbed TLS Contributors' under the
 #' 'Mbed TLS' Trusted Firmware Project at
-#' \url{https://www.trustedfirmware.org/projects/mbed-tls}.
+#' <https://www.trustedfirmware.org/projects/mbed-tls>.
 #'
-#' @seealso \code{\link{base64enc}}
+#' @seealso [base64enc()]
 #'
 #' @examples
 #' base64dec(base64enc("secret base"))

diff --git a/R/secret.R b/R/secret.R
@@ -27,7 +27,7 @@
 #'
 #' @encoding UTF-8
 #' @author Charlie Gao \email{charlie.gao@@shikokuchuo.net}
-#'     (\href{https://orcid.org/0000-0002-0750-061X}{ORCID})
+#'     ([ORCID](https://orcid.org/0000-0002-0750-061X))
 #'
 #' @useDynLib secretbase, .registration = TRUE
 #'
@@ -42,14 +42,13 @@
 #' @param x object to hash. A character string or raw vector (without
 #'   attributes) is hashed \sQuote{as is}. All other objects are stream hashed
 #'   using R serialization (but without allocation of the serialized object).
-#' @param bits [default 256L] output size of the returned hash. Must be one of
-#'   224, 256, 384 or 512.
-#' @param convert [default TRUE] if TRUE, the hash is converted to its hex
-#'   representation as a character string, if FALSE, output directly as a raw
-#'   vector, or if NA, a vector of (32-bit) integer values.
+#' @param bits integer output size of the returned hash. Must be one of 224,
+#'   256, 384 or 512.
+#' @param convert logical TRUE to convert the hash to its hex representation as
+#'   a character string, FALSE to return directly as a raw vector, or NA to
+#'   return as a vector of (32-bit) integers.
 #' @param file character file name / path. If specified, \sQuote{x} is ignored.
-#'   The file is stream hashed, thus capable of handling files larger than
-#'   memory.
+#'   The file is stream hashed, hence files larger than memory are permitted.
 #'
 #' @return A character string, raw or integer vector depending on
 #'   \sQuote{convert}.
@@ -66,7 +65,7 @@
 #' 
 #' This implementation is based on one by 'The Mbed TLS Contributors' under the
 #' 'Mbed TLS' Trusted Firmware Project at
-#' \url{https://www.trustedfirmware.org/projects/mbed-tls}.
+#' <https://www.trustedfirmware.org/projects/mbed-tls>.
 #'
 #' @examples
 #' # SHA3-256 hash as character string:
@@ -104,8 +103,8 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file)
 #' \sQuote{convert} to NA.
 #'
 #' @inheritParams sha3
-#' @param bits [default 256L] output size of the returned hash. Must be between
-#'   8 and 2^24 and coercible to integer.
+#' @param bits integer output size of the returned hash. Value must be between 8
+#'   and 2^24.
 #'
 #' @return A character string, raw or integer vector depending on
 #'   \sQuote{convert}.
@@ -115,7 +114,7 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file)
 #' @references
 #' This implementation is based on one by 'The Mbed TLS Contributors' under the
 #' 'Mbed TLS' Trusted Firmware Project at
-#' \url{https://www.trustedfirmware.org/projects/mbed-tls}.
+#' <https://www.trustedfirmware.org/projects/mbed-tls>.
 #'
 #' @examples
 #' # SHAKE256 hash as character string:
@@ -158,7 +157,7 @@ shake256 <- function(x, bits = 256L, convert = TRUE, file)
 #' 
 #' This implementation is based on one by 'The Mbed TLS Contributors' under the
 #' 'Mbed TLS' Trusted Firmware Project at
-#' \url{https://www.trustedfirmware.org/projects/mbed-tls}.
+#' <https://www.trustedfirmware.org/projects/mbed-tls>.
 #'
 #' @examples
 #' # Keccak-256 hash as character string:
@@ -193,10 +192,9 @@ keccak <- function(x, bits = 256L, convert = TRUE, file)
 #' key is supplied.
 #'
 #' @inheritParams sha3
-#' @param key [default NULL] If NULL, the SHA-256 hash of \sQuote{x} is
-#'   returned. Alternatively, supply a character string or raw vector as a
-#'   secret key to generate an HMAC. Note: for character vectors, only the first
-#'   element is used.
+#' @param key if NULL, the SHA-256 hash of \sQuote{x} is returned. If a
+#'   character string or raw vector, this is used as a secret key to generate an
+#'   HMAC. Note: for character vectors, only the first element is used.
 #'
 #' @return A character string, raw or integer vector depending on
 #'   \sQuote{convert}.
@@ -206,11 +204,11 @@ keccak <- function(x, bits = 256L, convert = TRUE, file)
 #' @references
 #' The SHA-256 Secure Hash Standard was published by the National Institute of
 #' Standards and Technology (NIST) in 2002 at
-#' \url{https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}.
+#' <https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf>.
 #' 
 #' This implementation is based on one by 'The Mbed TLS Contributors' under the
 #' 'Mbed TLS' Trusted Firmware Project at
-#' \url{https://www.trustedfirmware.org/projects/mbed-tls}.
+#' <https://www.trustedfirmware.org/projects/mbed-tls>.
 #'
 #' @examples
 #' # SHA-256 hash as character string:
@@ -243,11 +241,10 @@ sha256 <- function(x, key = NULL, convert = TRUE, file)
 #' not a cryptographic hash algorithm.
 #'
 #' @inheritParams sha3
-#' @param key [default NULL] a character string or raw vector comprising the 16
-#'   byte (128 bit) key data, or else NULL which is equivalent to '0'. If a
-#'   longer vector is supplied, only the first 16 bytes are used, and if
-#'   shorter, padded with trailing '0'. Note: for character vectors, only the
-#'   first element is used.
+#' @param key a character string or raw vector comprising the 16 byte (128 bit)
+#'   key data, or else NULL which is equivalent to '0'. If a longer vector is
+#'   supplied, only the first 16 bytes are used, and if shorter, padded with
+#'   trailing '0'. Note: for character vectors, only the first element is used.
 #'
 #' @return A character string, raw or integer vector depending on
 #'   \sQuote{convert}.
@@ -258,14 +255,14 @@ sha256 <- function(x, key = NULL, convert = TRUE, file)
 #' The SipHash family of cryptographically-strong pseudorandom functions (PRFs)
 #' are described in 'SipHash: a fast short-input PRF', Jean-Philippe Aumasson
 #' and Daniel J. Bernstein, Paper 2012/351, 2012, Cryptology ePrint Archive at
-#' \url{https://ia.cr/2012/351}.
+#' <https://ia.cr/2012/351>.
 #' 
 #' This implementation is based on the SipHash streaming implementation by
 #' Daniele Nicolodi, David Rheinsberg and Tom Gundersen at
-#' \url{https://github.com/c-util/c-siphash}. This is in turn based on the
+#' <https://github.com/c-util/c-siphash>. This is in turn based on the
 #' SipHash reference implementation by Jean-Philippe Aumasson and Daniel J.
 #' Bernstein released to the public domain at
-#' \url{https://github.com/veorq/SipHash}.
+#' <https://github.com/veorq/SipHash>.
 #'
 #' @examples
 #' # SipHash-1-3 hash as character string:

diff --git a/README.md b/README.md
@@ -158,7 +158,7 @@ Serialized objects:
 
 ``` r
 base64enc(data.frame())
-#> [1] "WAoAAAADAAQEAQADBQAAAAAFVVRGLTgAAAMTAAAAAAAABAIAAAABAAQACQAAAAVuYW1lcwAAABAAAAAAAAAEAgAAAAEABAAJAAAACXJvdy5uYW1lcwAAAA0AAAAAAAAEAgAAAAEABAAJAAAABWNsYXNzAAAAEAAAAAEABAAJAAAACmRhdGEuZnJhbWUAAAD+"
+#> [1] "WAoAAAADAAQEAgADBQAAAAAFVVRGLTgAAAMTAAAAAAAABAIAAAABAAQACQAAAAVuYW1lcwAAABAAAAAAAAAEAgAAAAEABAAJAAAACXJvdy5uYW1lcwAAAA0AAAAAAAAEAgAAAAEABAAJAAAABWNsYXNzAAAAEAAAAAEABAAJAAAACmRhdGEuZnJhbWUAAAD+"
 base64dec(base64enc(data.frame()), convert = NA)
 #> data frame with 0 columns and 0 rows
 ```

diff --git a/man/base64dec.Rd b/man/base64dec.Rd
diff --git a/man/base64enc.Rd b/man/base64enc.Rd
diff --git a/man/keccak.Rd b/man/keccak.Rd
diff --git a/man/secretbase-package.Rd b/man/secretbase-package.Rd
diff --git a/man/sha256.Rd b/man/sha256.Rd
diff --git a/man/sha3.Rd b/man/sha3.Rd
diff --git a/man/shake256.Rd b/man/shake256.Rd