Store tag descriptions in inst/tags.yml

Fixes #1375

DESCRIPTION

@@ -42,6 +42,7 @@ Suggests:
     R.oo,
     rmarkdown,
     testthat (>= 3.1.2),
+    yaml
 LinkingTo: 
     cpp11
 VignetteBuilder: 

NAMESPACE

@@ -240,6 +240,8 @@ export(tag_two_part)
 export(tag_value)
 export(tag_words)
 export(tag_words_line)
+export(tags_list)
+export(tags_metadata)
 export(update_collate)
 export(vignette_roclet)
 export(warn_roxy_tag)

NEWS.md

@@ -1,5 +1,9 @@
 # roxygen2 (development version)
 
+* New `tags_list()` lists all tags defined by roxygen2 and
+  `tags_metadata()` provides some useful information about them for
+  use by (e.g.) IDEs (#1375).
+
 * roxygen2 now only only includes PDF figures generated via markdown in
   the PDF manual, and only includes SVG figures generated via markdown
   in the HTML manual (#1399).

R/tag-metadata.R

@@ -0,0 +1,28 @@
+#' Access metadata about built-in tags
+#'
+#' @export
+#' @keywords internal
+tags_list <- function(built_in = TRUE) {
+  if (isTRUE(built_in)) {
+    methods <- attr(methods('roxy_tag_parse'), "info")
+    methods <- methods[methods$from == "roxygen2", ]
+    methods <- rownames(methods)[-1]
+  } else {
+    # Needed since the info attribute doesn't seem to exist
+    # during R CMD check
+    methods <- as.character(methods('roxy_tag_parse'))[-1]
+  }
+  sort(sub('.*\\.roxy_tag_', '', methods))
+}
+
+#' @export
+#' @rdname tags_list
+tags_metadata <- function() {
+  check_installed("yaml")
+
+  yaml::read_yaml(yaml_path())
+}
+
+yaml_path <- function() {
+  system.file("tags.yml", package = "roxygen2")
+}

R/tag-parser.R

@@ -29,6 +29,12 @@ tag_value <- function(x) {
   }
 }
 
+# Also recorded in tags.yml
+inherit_components <- c(
+  "params", "return", "title", "description", "details", "seealso",
+  "sections", "references", "examples", "author", "source", "note"
+)
+
 #' @export
 #' @rdname tag_parsers
 tag_inherit <- function(x) {
@@ -42,9 +48,7 @@ tag_inherit <- function(x) {
     pieces <- str_split(str_trim(x$raw), "\\s+")[[1]]
     fields <- pieces[-1]
 
-    # Also recorded in `rd.Rmd`
-    all <- c("params", "return", "title", "description", "details", "seealso",
-      "sections", "references", "examples", "author", "source", "note")
+    all <- inherit_components
     if (length(fields) == 0) {
       fields <- all
     } else {