From 56c8a4ff9a67f9eafc85ca17b7cc7bd63ecbb9a3 Mon Sep 17 00:00:00 2001
From: Kevin Ushey <kevinushey@gmail.com>
Date: Wed, 4 Sep 2024 15:08:31 -0700
Subject: [PATCH] export dotify; update docs

---
 DESCRIPTION        |  3 ++-
 NAMESPACE          |  1 +
 NEWS.md            |  3 +++
 R/destructure.R    |  7 ++++---
 R/dotify.R         | 25 +++++++++++++++++++++----
 R/utils.R          |  4 ++++
 man/destructure.Rd |  3 +++
 man/dotify.Rd      | 28 ++++++++++++++++++++++++++++
 8 files changed, 66 insertions(+), 8 deletions(-)
 create mode 100644 R/utils.R
 create mode 100644 man/dotify.Rd

diff --git a/DESCRIPTION b/DESCRIPTION
index 8d30a16..443f5ce 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -2,7 +2,8 @@ Package: dotty
 Type: Package
 Title: The Unpacking Dot Operator
 Version: 0.1.0.9000
-Authors@R: c(
+Authors@R:
+  c(
     person(
       "Kevin", "Ushey",
       email = "kevinushey@gmail.com",
diff --git a/NAMESPACE b/NAMESPACE
index de76132..eaef960 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -7,6 +7,7 @@ S3method(format,dotty)
 S3method(print,dotty)
 export(.)
 export(destructure)
+export(dotify)
 importFrom(utils,globalVariables)
 importFrom(utils,head)
 importFrom(utils,tail)
diff --git a/NEWS.md b/NEWS.md
index 1879b3f..913143b 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,6 +1,9 @@
 
 # dotty 0.2.0  (UNRELEASED)
 
+- `dotty::dotify()` is now exported for use by R packages which would
+  like to use `dotty` internally. (#1)
+
 
 # dotty 0.1.0
 
diff --git a/R/destructure.R b/R/destructure.R
index 648a340..a08c001 100644
--- a/R/destructure.R
+++ b/R/destructure.R
@@ -1,16 +1,17 @@
 
 #' Destructure an Object
-#' 
+#'
 #' `destructure` is primarily used to help define how an
 #' object should be prepared, or transformed, prior to a
 #' destructuring assignment. This can be relevant for
 #' objects which have unique subsetting semantics -- for
 #' example, [numeric_version] objects.
-#' 
+#'
 #' Packages which would like to define special destructring
 #' semantics for certain object classes can implement
 #' methods for this class.
-#' 
+#'
+#' @param object An \R object.
 #' @export
 destructure <- function(object) {
   UseMethod("destructure")
diff --git a/R/dotify.R b/R/dotify.R
index 1759128..5811643 100644
--- a/R/dotify.R
+++ b/R/dotify.R
@@ -1,8 +1,25 @@
 
-`%||%` <- function(x, y) {
-  if (is.null(x)) y else x
-}
-
+#' Dotify an R Package
+#'
+#' When using `dotty` within an R package, you might see **NOTE**s during
+#' `R CMD check` of the form:
+#'
+#' ```
+#' N  checking R code for possible problems (1.8s)
+#'    <package>: no visible binding for global variable <variable>
+#'    Undefined global functions or variables:
+#'      <variable>
+#' ```
+#'
+#' This occurs because the [codetools] package, which is used for static
+#' analysis of \R code during `R CMD check`, does not recognize that e.g.
+#' `.[apple] <- 42` would create a variable called `apple` in the current
+#' scope. Calling `dotty::dotify()` in your package's `.onLoad()` will
+#' allow `dotty` to patch `codetools` in a way that will allow it to
+#' understand `dotty` usages, and so prevent these `R CMD check` notes
+#' from being emitted.
+#'
+#' @export
 dotify <- function() {
 
   # allow us to be disabled if necessary
diff --git a/R/utils.R b/R/utils.R
new file mode 100644
index 0000000..867ac98
--- /dev/null
+++ b/R/utils.R
@@ -0,0 +1,4 @@
+
+`%||%` <- function(x, y) {
+  if (is.null(x)) y else x
+}
diff --git a/man/destructure.Rd b/man/destructure.Rd
index 18d3198..0d3c5ca 100644
--- a/man/destructure.Rd
+++ b/man/destructure.Rd
@@ -6,6 +6,9 @@
 \usage{
 destructure(object)
 }
+\arguments{
+\item{object}{An \R object.}
+}
 \description{
 `destructure` is primarily used to help define how an
 object should be prepared, or transformed, prior to a
diff --git a/man/dotify.Rd b/man/dotify.Rd
new file mode 100644
index 0000000..4915cc2
--- /dev/null
+++ b/man/dotify.Rd
@@ -0,0 +1,28 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/dotify.R
+\name{dotify}
+\alias{dotify}
+\title{Dotify an R Package}
+\usage{
+dotify()
+}
+\description{
+When using `dotty` within an R package, you might see **NOTE**s during
+`R CMD check` of the form:
+}
+\details{
+```
+N  checking R code for possible problems (1.8s)
+   <package>: no visible binding for global variable <variable>
+   Undefined global functions or variables:
+     <variable>
+```
+
+This occurs because the [codetools] package, which is used for static
+analysis of \R code during `R CMD check`, does not recognize that e.g.
+`.[apple] <- 42` would create a variable called `apple` in the current
+scope. Calling `dotty::dotify()` in your package's `.onLoad()` will
+allow `dotty` to patch `codetools` in a way that will allow it to
+understand `dotty` usages, and so prevent these `R CMD check` notes
+from being emitted.
+}