cleanup in preparation for 0.1.0 CRAN release (#14)

Author: dgkf

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: roxytypes
-Title: Provides Typed Parameter Tags for Integration with 'roxygen2'
-Version: 0.0.0.9003
+Title: Typed Parameter Tags for Integration with 'roxygen2'
+Version: 0.1.0
 Authors@R:
     c(
       person(
@@ -9,12 +9,17 @@ Authors@R:
         role = c("aut", "cre")
       )
     )
-Description: Provides typed parameter tags for integration with 'roxygen2'.
+Description: Provides typed parameter documentation tags for integration
+    with 'roxygen2'. Typed parameter tags provide a consistent interface for
+    annotating expected types for parameters and returned values. Tools for
+    converting from existing styles are also provided to easily adapt projects
+    which implement typed documentation by convention rather than tag. Use the
+    default format or provide your own.
 License: MIT + file LICENSE
 Encoding: UTF-8
 URL:
     https://github.com/openpharma/roxytypes,
-    https://openpharma.github.io/roxytypes
+    https://openpharma.github.io/roxytypes/
 BugReports:
     https://github.com/openpharma/roxytypes/issues
 Imports:
@@ -27,9 +32,6 @@ Suggests:
     testthat
 Enhances:
     roxylint
-Remotes:
-    openpharma/roxylint
 Config/Needs/documentation:
-    roxytypes
-Roxygen: list(markdown = TRUE, packages = "roxytypes")
-RoxygenNote: 7.2.3
+    roxylint
+RoxygenNote: 7.3.1

NEWS.md

@@ -1,9 +1,13 @@
-# roxytypes 0.0.0.dev
+# roxytypes v0.1.0
+
+* first CRAN release
+
+# roxytypes v0.0.0.9000
 
 * Automatically apply default formatting based on field types. For `type` 
-  fields, this will perform a default formatting 
-  (see `roxytypes:::as.character.roxy_tag_field_type`). To use another 
-  formatting style in a config, use `"{unclass(type)}"` (@dgkf #13)
+  fields, this will perform a default formatting  (see
+  `roxytypes:::as.character.roxy_tag_field_type`). To use another formatting
+  style in a config, use `"{unclass(type)}"` (@dgkf #13)
 
 * Improved the stability of some custom formatting syntax, and improved
   documentation for user-provided custom formatting functions. (@dgkf #11)

R/convert.R

@@ -42,10 +42,12 @@
 #' }
 #'
 #' @export
-convert <- function(path = ".",
-  format = config(path, refresh = TRUE, cache = FALSE)$format, ...,
-  unmatched = FALSE, verbose = interactive()) {
-
+convert <- function(
+    path = ".",
+    format = config(path, refresh = TRUE, cache = FALSE)$format,
+    ...,
+    unmatched = FALSE,
+    verbose = interactive()) {
   # process format to build expression for matching tag decriptions
   format <- build_format_regex(format, ...)
 
@@ -62,11 +64,15 @@ convert <- function(path = ".",
   edits <- build_convert_edits(format, tags, unmatched = unmatched)
 
   continue <- 3
-  if (nrow(edits) > 0 && verbose) repeat {
-    preview_convert_edits(edits, n = continue)
-    continue <- convert_continue_prompt()
-    if (isTRUE(continue)) break  # continue with edits
-    if (!is.numeric(continue)) return(invisible(FALSE))  # abort
+  if (nrow(edits) > 0 && verbose) {
+    repeat {
+      preview_convert_edits(edits, n = continue)
+      continue <- convert_continue_prompt()
+      if (isTRUE(continue)) break # continue with edits
+      if (!is.numeric(continue)) {
+        return(invisible(FALSE))
+      } # abort
+    }
   }
 
   n_edits <- make_convert_edits(edits)

R/convert_cli.R

@@ -3,16 +3,6 @@
 #' Various functions for supporting conversion from standard roxygen tags to
 #' `@typed` tags.
 #'
-#' @typed format: string
-#'   A regular expression to use to match existing param definitions.
-#' @typed tags: list(roxy_tag)
-#'   A selection of [roxygen2::roxy_tag()]s that should be considered or
-#'   converted.
-#' @typed unmatched: logical[1]
-#'   Indicates whether `@param` tags that don't match the expected pattern
-#'   should be converted anyways. In such cases, their entire description is
-#'   migrated to a new `@typed` description and the new `@typed` tag's type is
-#'   left blank.
 #' @typed edit,edits: data.frame
 #'   As produced by `convert_edit_df`. Contains the edit source file, starting
 #'   line number, number of original lines modified, the new content to insert
@@ -64,9 +54,6 @@ convert_continue_prompt <- function() {
 #' @describeIn convert_helpers
 #' Preview diffs after applying conversion rules
 #'
-#' @param tags A list of [roxygen2::roxy_tag()]s to preview
-#' @param n The number of tags to preview
-#'
 #' @return `NULL`
 #'
 preview_convert_edits <- function(edits, n = 1) {

R/convert_config.R

@@ -1,6 +1,6 @@
 #' Tools for modifying configuration files
 #'
-#' @typed path,root: character[1]
+#' @typed path: character[1]
 #'   A file path within the package directory.
 #' @typed dcf: data.frame
 #'   The result of [read.dcf()] on the package description file.

R/convert_re.R

@@ -27,6 +27,9 @@
 #'   A regular expression to use to match a parameter description. By default,
 #'   matches any string.
 #'
+#' @typedreturn character[1]:
+#'   A regular expression string, built from component sub-expressions.
+#'
 #' @examples
 #' re <- roxytypes:::build_format_regex(
 #'   "{as}{any}{bs}",
@@ -37,9 +40,12 @@
 #'
 #' roxytypes:::regex_capture(re, "aaaa\n\nbb", perl = TRUE)
 #'
-build_format_regex <- function(format, format_re, ...,
-  type = re_backticked(), description = re_any()) {
-
+build_format_regex <- function(
+    format,
+    format_re,
+    ...,
+    type = re_backticked(),
+    description = re_any()) {
   keywords <- list(..., type = type, description = description)
   keywords <- mapply(
     function(k, v) glue::glue("(?<{k}>{v})"),

R/state_config.R

@@ -7,13 +7,6 @@
 #' documentation is being built to avoid constantly parsing configurations
 #' during evaluation of each tag.
 #'
-#' @typed x: roxy_tag
-#'   An internal, intermediate `roxygen2` tag object upon which to evaluate
-#'   configured behaviors.
-#' @typed config: list(format= )
-#'   A list of configuration parameters.
-#' @typed e: environment
-#'   A package environment used while running `roxygen2`.
 #' @typed path: character[1]
 #'   A file path to use when searching for a config file. Either the file path
 #'   to a `DESCRIPTION` or the root path of a package, depending on the context
@@ -50,8 +43,8 @@ CONFIG <- paste0(".", utils::packageName(), "_config")  # nolint
 #' @typedreturn list
 #'   A named list of configured behaviors.
 #'
-#' @importFrom cli cli_alert_info
 #' @keywords internal
+#' @importFrom cli cli_alert_info
 config <- function(path = getwd(), refresh = FALSE, cache = TRUE) {
   roxytypes_config <- roxygen2::roxy_meta_get("roxytypes")
   if (!refresh && length(roxytypes_config) > 0)
@@ -111,8 +104,8 @@ config_from_desc <- function(path = ".") {
 #' @describeIn config_helpers
 #' Load a configuration from a dotfile
 #'
-#' @importFrom utils packageName
 #' @keywords internal
+#' @importFrom utils packageName
 config_from_file <- function(path = ".") {
   pattern <- "^meta\\.[rR]"
 

R/tag_typed.R

@@ -83,6 +83,8 @@ NULL
 #' Parse a `@typed` tag and return parsed components as value
 #'
 #' @inheritParams roxygen2::roxy_tag_parse
+#' @typedreturn roxygen2 tag
+#'   A parsed `roxygen2` `@typed` rd_tag.
 #'
 #' @importFrom roxygen2 roxy_tag_parse
 #' @exportS3Method
@@ -108,6 +110,8 @@ roxy_tag_parse.roxy_tag_typed <- function(x) {  # nolint
 #' Push typed fields into `@param` section
 #'
 #' @inheritParams roxygen2::roxy_tag_rd
+#' @typedreturn [roxygen2::rd_section]
+#'   A `roxygen2` "param" rd_section with formatted type information.
 #'
 #' @importFrom glue glue
 #' @importFrom roxygen2 roxy_tag_rd

R/tag_typedreturn.R

@@ -3,9 +3,8 @@
 #' The `@typedreturn` tag introduces a syntax for defining return types as a
 #' `roxygen2` tag.
 #'
-#' There are a couple important syntactic features:
+#' There is one important syntactic features:
 #'
-#'   * `:` delimiter between the variable name and type.
 #'   * `\n` after the type to separate it from the description.
 #'
 #' @usage
@@ -21,6 +20,8 @@ NULL
 #' Parse a `@typedreturn` tag and return parsed components as value
 #'
 #' @inheritParams roxygen2::roxy_tag_parse
+#' @typedreturn roxygen2 tag
+#'   A parsed `roxygen2` `@typedreturn` rd_tag.
 #'
 #' @importFrom roxygen2 roxy_tag_parse
 #' @exportS3Method
@@ -45,6 +46,8 @@ roxy_tag_parse.roxy_tag_typedreturn <- function(x) {  # nolint
 #' Push typed fields into `@param` section
 #'
 #' @inheritParams roxygen2::roxy_tag_rd
+#' @typedreturn [roxygen2::rd_section]
+#'   A `roxygen2` `@value` rd_tag with formatted type information.
 #'
 #' @importFrom glue glue
 #' @importFrom roxygen2 roxy_tag_rd

cran-comments.md

@@ -0,0 +1,21 @@
+# roxytypes
+
+## Foreseable CRAN concerns:
+
+### Examples for Non-Exported Functions
+
+All uses of `:::` are to access non-exported functions from within this package.
+They are only used for the purpose of providing example code. If possible,
+I would like to keep these examples as I find they are a useful resource for
+would-be contributors and users filing bug reports.
+
+### Ensuring that Functions do not Write to the User's Home
+
+There is one function (`convert()`) that has the expressed purpose of
+modifying a package's code (converting from roxygen `@param` tags to roxytype
+`@typed` tags, a drop-in replacement for use with this package). When used
+interactively, users are provided with a prompt that displays proposed changes
+before any changes are made.
+
+Tests all write to a sub-directory using `tmpfile()` to generate a unique
+temporary directory for each test fixture.