diff --git a/R/global_roclet.R b/R/global_roclet.R
index c3b327f..c296f7c 100644
--- a/R/global_roclet.R
+++ b/R/global_roclet.R
@@ -1,8 +1,33 @@
 #' Roclet: global
 #'
+#' @description
+#' This roclet automates [utils::globalVariables()] declaration from @global
+#' and @autoglobal roxygen tags.
+#'
+#' Package authors will not typically need to invoke [global_roclet()] directly.
+#' Global roclet instances are created by `roxygen2` during [roxygen2::roxygenise()]
+#' (or [devtools::document()]).
+#'
 #' @importFrom roxygen2 roclet
+#' @return A [roxygen2::roclet()] instance for declaring [utils::globalVariables()]
+#' during [roxygen2::roxygenise()]
 #' @export
-global_roclet <- function() roxygen2::roclet("global")
+#'
+#' @examples
+#' #' @autoglobal
+#' foo <- function(x) {
+#'   # bar isn't declared -> add to utils::globalVariables()
+#'   subset(x, bar == 4)
+#' }
+#'
+#' #' @global bar
+#' foo <- function(x) {
+#'   # bar is explicitly defined as a global -> add to utils::globalVariables()
+#'   subset(x, bar == 4)
+#' }
+global_roclet <- function() {
+  roxygen2::roclet("global")
+}
 
 #' @importFrom roxygen2 roclet_process
 #' @export
diff --git a/man/global_roclet.Rd b/man/global_roclet.Rd
index f96bf63..6825246 100644
--- a/man/global_roclet.Rd
+++ b/man/global_roclet.Rd
@@ -6,6 +6,28 @@
 \usage{
 global_roclet()
 }
+\value{
+A \code{\link[roxygen2:roclet]{roxygen2::roclet()}} instance for declaring \code{\link[utils:globalVariables]{utils::globalVariables()}}
+during \code{\link[roxygen2:roxygenize]{roxygen2::roxygenise()}}
+}
 \description{
-Roclet: global
+This roclet automates \code{\link[utils:globalVariables]{utils::globalVariables()}} declaration from @global
+and @autoglobal roxygen tags.
+
+Package authors will not typically need to invoke \code{\link[=global_roclet]{global_roclet()}} directly.
+Global roclet instances are created by \code{roxygen2} during \code{\link[roxygen2:roxygenize]{roxygen2::roxygenise()}}
+(or \code{\link[devtools:document]{devtools::document()}}).
+}
+\examples{
+#' @autoglobal
+foo <- function(x) {
+  # bar isn't declared -> add to utils::globalVariables()
+  subset(x, bar == 4)
+}
+
+#' @global bar
+foo <- function(x) {
+  # bar is explicitly defined as a global -> add to utils::globalVariables()
+  subset(x, bar == 4)
+}
 }