Support method-level @returns (#1818)

Includes some refactoring to make it clear that there are three types of R6 tags: tags that belong to the class, tags that belong to a method, and tags that are handled elsewhere.

Also fixes a dev-only bug that caused method descriptions/details to get repeated in the class docs.

Fixes #1148

Author: hadley

NEWS.md

@@ -3,6 +3,7 @@
 * `@examplesIf` now warns when there is no example code after the condition (#1695).
 * `tag_words_line()` is deprecated in favour of `tag_words()`, which now checks for single-line content by default. Use `tag_words(x, multiline = TRUE)` or `tag_value(x, multiline = TRUE)` if your tag legitimately spans multiple lines.
 * R6 improvements:
+  * `@returns` now works as a method-level tag in R6 classes, just like `@return` (#1148).
   * The "Super classes" section now omits the `pkg::` prefix for parent classes from the same package, making the inheritance chain easier to read (#1567).
   * R6 classes with only active bindings and `cloneable = FALSE` no longer error during documentation (#1610).
   * `@example` (singular, with a file path) now works correctly in R6 class documentation (#1158).

R/rd-r6-methods-self.R

@@ -119,9 +119,9 @@ r6_method_from_row <- function(method, alias, block) {
 
   params <- r6_resolve_params(method, block)
 
-  ret_tags <- keep(tags, \(t) t$tag == "return")
+  ret_tags <- keep(tags, \(t) t$tag %in% c("return", "returns"))
   if (length(ret_tags) > 1) {
-    warn_roxy_block(block, "Must use one @return per R6 method")
+    warn_roxy_block(block, "Must use one @return(s) per R6 method")
   }
   ret <- if (length(ret_tags) > 0) ret_tags[[1]]$val else NULL
 

R/rd-r6-methods.R

@@ -43,13 +43,9 @@ r6_extract_methods <- function(r6data, alias, block) {
   methods_df$tags <- replicate(nrow(methods_df), list(), simplify = FALSE)
 
   # Associate inline tags with methods
-  r6_tags <- c("description", "details", "param", "return", "examples")
   for (i in seq_along(block$tags)) {
     tag <- block$tags[[i]]
-    if (is.na(tag$line) || tag$line < block$line) {
-      next
-    }
-    if (!tag$tag %in% r6_tags) {
+    if (r6_tag_type(tag, block) != "method") {
       next
     }
     meth <- find_method_for_tag(methods_df, tag)

R/rd-r6.R

@@ -3,7 +3,7 @@ topic_add_r6_methods <- function(rd, block, env, base_path) {
 
   # Add class-level tags
   for (tag in block$tags) {
-    if (is_class_tag(tag, block)) {
+    if (r6_tag_type(tag, block) == "class") {
       rd$add(roxy_tag_rd(tag, env = env, base_path = base_path))
     }
   }
@@ -20,12 +20,23 @@ topic_add_r6_methods <- function(rd, block, env, base_path) {
   }
 }
 
-is_class_tag <- function(tag, block) {
-  if (tag$tag %in% c("param", "field")) {
-    FALSE
-  } else if (tag$tag %in% c("description", "details", "return", "examples")) {
-    !is.na(tag$line) && tag$line >= block$line
+# Classify an R6 block tag:
+# - "class": top-level Rd (e.g. @title, @description before class body)
+# - "method": inline tag associated with a method
+# - "other": @field/@param tags consumed by field/param extraction
+r6_tag_type <- function(tag, block) {
+  inline <- !is.na(tag$line) && tag$line >= block$line
+  method_tags <- c(
+    "description", "details", "param", "return", "returns", "examples"
+  )
+
+  if (tag$tag == "field") {
+    "other"
+  } else if (tag$tag %in% method_tags && inline) {
+    "method"
+  } else if (tag$tag == "param") {
+    "other"
   } else {
-    TRUE
+    "class"
   }
 }

man/RoxyTopic.Rd

@@ -1,3 +1,10 @@
+# warns about multiple @return(s) tags
+
+    Code
+      docs <- r6_doc(text)
+    Message
+      x <text>:3: Must use one @return(s) per R6 method.
+
 # warns about undocumented params
 
     Code

tests/testthat/_snaps/rd-r6-methods-self.md

@@ -8,23 +8,14 @@
       \name{A}
       \alias{A}
       \title{Class A}
-      \value{
-      A value.
-      }
       \description{
-      A method 1.
-      
-      Method 2 description.
-      
-      Method 3.
+      Class A description.
       }
       \details{
-      Method 2 details.
+      Class A details
       }
       \examples{
       a <- A$new()
-      ## Example for meth1
-      ## Example for meth2
       
       ## ------------------------------------------------
       ## Method `A$meth1`
@@ -185,9 +176,10 @@
       \alias{B}
       \title{Class B}
       \description{
-      B method 1.
-      
-      B method 4.
+      Class B Description.
+      }
+      \details{
+      Class B details.
       }
       \section{Super class}{
       \code{A} -> \code{B}
@@ -291,9 +283,10 @@
       \alias{C}
       \title{Class C}
       \description{
-      C method 2.
-      
-      C method 5.
+      Class C Description.
+      }
+      \details{
+      Class C details.
       }
       \section{Super classes}{
       \code{A} -> \code{B} -> \code{C}
@@ -366,4 +359,3 @@
       
       }
       }
-

tests/testthat/_snaps/rd-r6.md

@@ -24,6 +24,35 @@ test_that("r6_method_from_row extracts all components", {
   expect_equal(method$examples, "c$greet('world')")
 })
 
+test_that("@returns works as method-level tag (#1148)", {
+  text <- "
+    #' Class
+    C <- R6::R6Class('C', cloneable = FALSE,
+      public = list(
+        #' @description Run.
+        #' @returns The result.
+        run = function() 1
+      )
+    )"
+  docs <- r6_doc(text)
+  expect_equal(docs$methods$self[[1]]$return, "The result.")
+})
+
+test_that("warns about multiple @return(s) tags", {
+  text <- "
+    #' Class
+    C <- R6::R6Class('C', cloneable = FALSE,
+      public = list(
+        #' @description Run.
+        #' @return First.
+        #' @returns Second.
+        run = function() 1
+      )
+    )"
+  expect_snapshot(docs <- r6_doc(text))
+  expect_equal(docs$methods$self[[1]]$return, "First.")
+})
+
 test_that("warns about undocumented params", {
   text <- "
     #' Class