support custom family prefixes (closes r-lib#830)

NEWS.md

@@ -1,5 +1,13 @@
 # roxygen2 (development version)
 
+* A system for providing custom roxygen2 metadata is now available.
+  If the file "man-roxygen/roxygen-meta.R" is available, it will be
+  evaluated. Its evaluation should produce an R list, mapping roxygen
+  option names to values. Currently, only 'family.prefix' is recognized:
+  this field should itself be an R list, mapping family names to the
+  appropriate prefixes to be used in the generated R documentation
+  (as opposed to the default 'Other family: '). (#830, @kevinushey)
+
 # roxygen2 6.1.1
 
 * Now specifically imports recent version of desc package (>= 1.2.0) to

R/meta.R

@@ -0,0 +1,39 @@
+
+.roxygen_meta <- new.env(parent = emptyenv())
+
+roxy_meta_read <- function(name) {
+  .roxygen_meta[[name]]
+}
+
+roxy_meta_load <- function(base_path) {
+
+  meta_dir <- file.path(base_path, "man-roxygen")
+
+  pattern <- "^roxygen-meta[.][Rr]"
+  meta_files <- list.files(meta_dir, pattern = pattern, full.names = TRUE)
+  if (length(meta_files) == 0)
+    return(FALSE)
+
+  if (length(meta_files) > 1) {
+    warning("multiple roxygen-meta.R files found: using '",
+            basename(meta_files[[1]]),
+            "'")
+    meta_files <- meta_files[[1]]
+  }
+
+  result <- tryCatch(eval(parse(meta_files)), error = identity)
+  if (inherits(result, "error")) {
+    warning(result)
+    return(FALSE)
+  }
+
+  if (!is.list(result)) {
+    warning("evaluation of roxygen-meta.R did not return a list")
+    return(FALSE)
+  }
+
+  rm(list = ls(envir = .roxygen_meta), envir = .roxygen_meta)
+  list2env(result, envir = .roxygen_meta)
+  TRUE
+
+}

R/rd-family.R

@@ -1,3 +1,15 @@
+topics_process_family_prefix <- function(family) {
+
+  # read custom family prefix from roxygen meta
+  opts <- roxy_meta_read("family.prefix")
+  if (!is.null(opts[[family]]))
+    return(opts[[family]])
+
+  # default prefix
+  paste("Other ", family, ": ", sep = "")
+
+}
+
 topics_process_family <- function(topics) {
   family_index <- invert(topics$simple_values("family"))
   aliases <- topics$simple_values("alias")
@@ -19,7 +31,7 @@ topics_process_family <- function(topics) {
       }, FUN.VALUE = character(1))
       links <- paste(sort_c(by_file), collapse = ", ")
 
-      seealso <- paste("Other ", family, ": ", sep = "")
+      seealso <- topics_process_family_prefix(family)
       out <- strwrap(links, initial = seealso, width = 60, exdent = 2)
 
       topic$add_simple_field("seealso", paste(out, collapse = "\n"))

R/rd.R

@@ -71,6 +71,10 @@ roclet_process.roclet_rd <- function(x,
                                      env,
                                      base_path,
                                      global_options = list()) {
+
+  # Load roxygen metadata
+  roxy_meta_load(base_path)
+
   # Convert each block into a topic, indexed by filename
   topics <- RoxyTopics$new()
 

tests/testthat/test-rd-family.R

@@ -95,3 +95,29 @@ test_that("family also included in concepts", {
 
   expect_equal(out$get_field("concept")$values, "a")
 })
+
+test_that("custom family prefixes can be set", {
+
+  owd <- setwd(tempdir())
+  on.exit(setwd(owd), add = TRUE)
+
+  dir.create("man-roxygen")
+  write_lines(
+    "list(family.prefix = list(a = 'Custom prefix: '))",
+    "man-roxygen/roxygen-meta.R"
+  )
+
+  out <- roc_proc_text(rd_roclet(), "
+    #' foo
+    #' @family a
+    foo <- function() {}
+
+    #' bar
+    #' @family a
+    bar <- function() {}
+  ")[[1]]
+
+  seealso <- get_tag(out, "seealso")$values
+  expect_match(seealso, "^Custom prefix:")
+
+})