document installation & usage

README.md

@@ -1,2 +1,69 @@
-# roxyglobals
-
+<p align="right">
+  <a href="https://github.com/anthonynorth/roxyglobals/releases/latest">
+    <img src="https://img.shields.io/github/v/release/anthonynorth/roxyglobals?sort=semver&style=flat-square" alt="release">
+  </a>
+  <a href="https://www.tidyverse.org/lifecycle/#experimental">
+    <img src="https://img.shields.io/badge/lifecycle-experimental-orange?style=flat-square" alt="lifecycle" />
+  </a>
+</p>
+
+<h1 align="center">roxyglobals</h1>
+
+<p align="center">
+  Generate `utils::globalVariables()` from roxygen @global tags.
+</p>
+
+## Installation
+
+```r
+remotes::install_github("anthonynorth/roxyglobals@*release")
+```
+
+## Usage
+
+Add roxyglobals to an R package DESCRIPTION via:
+
+```r
+roxyglobals::use_roxyglobals()
+```
+
+Add @global to a function roxygen comment block, example:
+
+```r
+#' Summarise responses
+#'
+#' @name summarise_responses
+#' @param responses a data.frame of responses
+#'
+#' @global station_name station_type end_time start_time
+#' @export
+summarise_responses <- function(responses) {
+  # station_name, station_type, end_time, start_time need to be added to 
+  # utils::globalVariables() to keep R CMD CHECK happy
+  responses %>%
+    dplyr::group_by(station_name, station_type) %>%
+    dplyr::summarise(
+      count_responses = dplyr::n(),
+      total_hours = sum(
+        as.numeric(end_time - start_time, units = "hours"),
+        na.rm = TRUE
+      ),
+      .groups = "drop"
+    )
+}
+```
+
+Run `devtools::document()` to generate `utils::globalVariables()` in ./R/globals.R.
+
+Example ./R/globals.R
+
+```r
+# generated by: roxyglobals
+
+utils::globalVariables(c(
+  "end_time",
+  "start_time",
+  "station_name",
+  "station_type"
+))
+```