Inherit parameter/field documentation from superclass (#1833)

Fixes #996

Author: hadley

NAMESPACE

@@ -38,6 +38,7 @@ S3method(format,rd_section_formals)
 S3method(format,rd_section_format)
 S3method(format,rd_section_inherit)
 S3method(format,rd_section_inherit_dot_params)
+S3method(format,rd_section_inherit_params_args)
 S3method(format,rd_section_inherit_section)
 S3method(format,rd_section_keyword)
 S3method(format,rd_section_minidesc)
@@ -46,6 +47,7 @@ S3method(format,rd_section_note)
 S3method(format,rd_section_package)
 S3method(format,rd_section_param)
 S3method(format,rd_section_prop)
+S3method(format,rd_section_r6_class)
 S3method(format,rd_section_rawRd)
 S3method(format,rd_section_rcmethods)
 S3method(format,rd_section_reexport)
@@ -62,6 +64,7 @@ S3method(merge,rd_section)
 S3method(merge,rd_section_author)
 S3method(merge,rd_section_inherit)
 S3method(merge,rd_section_inherit_dot_params)
+S3method(merge,rd_section_inherit_params_args)
 S3method(merge,rd_section_inherit_section)
 S3method(merge,rd_section_minidesc)
 S3method(merge,rd_section_param)

NEWS.md

@@ -24,6 +24,7 @@
   * You can now use `@noRd` before an R6 method to suppress its documentation, and `@field name NULL` to suppress documentation for a field or active binding (#1067).
   * Inherited method links now only link to parent classes that have documentation, avoiding broken links when parent classes are undocumented (#963, #1155).
   * `initialize()` method parameters now automatically inherit documentation from `@field` tags with the same name, reducing the need to duplicate descriptions. Explicit `@param` tags still take precedence (#1004).
+  * R6 subclass methods now automatically inherit parameter documentation from the same-named superclass method when parameters are not documented locally. Fields and active bindings also inherit documentation from superclasses (#996).
 * New `needs_roxygenize()` provides a lightweight check that man pages are up-to-date by comparing modification times of `.Rd` files with their source files (#1411).
 * All generated links now use the same code path. This will lead to some minor differences when you re-document, but overall the links will now be more consistent (#1792).
 * Reexported functions now display with `()` appended (e.g., `fun()` instead of `fun`) on the reexports page, except for infix operators like `%>%` (#1222). They also use modern (>= 4.1.0) linking style.

R/rd-r6-field.R

@@ -10,11 +10,6 @@ r6_extract_field_tags <- function(block, r6data, type = c("field", "active")) {
   tags <- keep(block$tags, \(t) tag_is(t, "field") && !tag_has_name(t, other))
   docd <- unlist(lapply(tags, tag_names))
 
-  miss <- setdiff(expected, docd)
-  if (length(miss) > 0) {
-    warn_roxy_block(block, "Undocumented R6 {label}{?s}: {miss}")
-  }
-
   dup <- unique(docd[duplicated(docd)])
   if (length(dup) > 0) {
     warn_roxy_block(block, "R6 {label}{?s} documented multiple times: {dup}")
@@ -37,14 +32,29 @@ r6_extract_field_tags <- function(block, r6data, type = c("field", "active")) {
     )
   })
 
-  rd_r6_fields(items, type = type)
+  rd_r6_fields(items, type = type, expected = expected)
+}
+
+r6_field_names <- function(rd_fields) {
+  if (length(rd_fields) == 0) {
+    return(character())
+  }
+  labels <- map_chr(rd_fields, \(x) x$name)
+  trimws(unlist(strsplit(labels, ",")))
 }
 
 # Rd ---------------------------------------------------------------------------
 
-rd_r6_fields <- function(fields = list(), type = c("field", "active")) {
+rd_r6_fields <- function(
+  fields = list(),
+  type = c("field", "active"),
+  expected = character()
+) {
   type <- match.arg(type)
-  structure(list(fields = fields, type = type), class = "rd_r6_fields")
+  structure(
+    list(fields = fields, type = type, expected = expected),
+    class = "rd_r6_fields"
+  )
 }
 
 rd_r6_field <- function(name, description) {

R/rd-r6-methods-self.R

@@ -143,11 +143,17 @@ r6_method_from_row <- function(method, block) {
   )
 }
 
+# Resolve params within a class: method @param -> class-level @param -> @field.
+# Cross-class inheritance from parent classes is handled later by
+# r6_resolve_method_params().
 r6_resolve_params <- function(method, block) {
   tags <- method$tags[[1]]
-  par <- keep(tags, \(t) t$tag == "param")
-  mnames <- unlist(lapply(par, tag_names))
-  dup <- unique(mnames[duplicated(mnames)])
+  par_tags <- keep(tags, \(t) t$tag == "param")
+
+  params <- r6_tags_to_params(par_tags)
+  pnames <- r6_param_names(params)
+
+  dup <- unique(pnames[duplicated(pnames)])
   for (m in dup) {
     warn_roxy_block(
       block,
@@ -163,61 +169,52 @@ r6_resolve_params <- function(method, block) {
     return(list())
   }
 
-  # Add missing from class-level @param
-  miss <- setdiff(fnames, mnames)
-  is_in_cls <- map_lgl(
-    block$tags,
-    function(t) {
-      !is.na(t$line) &&
-        t$line < block$line &&
-        tag_is(t, "param") &&
-        tag_has_name(t, miss)
-    }
-  )
-  par <- c(par, block$tags[is_in_cls])
+  # 1. Add class-level @param
+  miss <- setdiff(fnames, pnames)
+  cls_tags <- keep(block$tags, function(t) {
+    !is.na(t$line) &&
+      t$line < block$line &&
+      tag_is(t, "param") &&
+      tag_has_name(t, miss)
+  })
+  params <- c(params, r6_tags_to_params(cls_tags))
 
-  # For initialize(), inherit from @field tags for any still-missing params
+  # 2. For initialize() only, inherit from @field
   if (method$name == "initialize") {
-    mnames <- unlist(lapply(par, tag_names))
-    miss <- setdiff(fnames, mnames)
+    miss <- setdiff(fnames, r6_param_names(params))
 
     if (length(miss) > 0) {
       field_tags <- keep(block$tags, function(t) {
         tag_is(t, "field") && tag_has_name(t, miss)
       })
-      field_as_param <- lapply(field_tags, function(t) {
-        val <- list(name = t$val$name, description = t$val$description)
-        roxy_generated_tag(block, "param", val)
-      })
-      par <- c(par, field_as_param)
+      params <- c(params, r6_tags_to_params(field_tags))
     }
   }
 
-  # Check if anything is still missing
-  mnames <- unlist(lapply(par, tag_names))
-  miss <- setdiff(fnames, mnames)
-  for (m in miss) {
-    warn_roxy_block(
-      block,
-      c(
-        "Must use one @param for each argument",
-        x = "${method$name}({m}) is not documented"
-      )
-    )
-  }
-
   # Order them according to formals
-  firstnames <- map_chr(par, \(t) tag_names(t)[[1]])
-  par <- par[order(match(firstnames, fnames))]
+  firstnames <- map_chr(
+    strsplit(map_chr(params, \(x) x$name), ","),
+    \(x) trimws(x[[1]])
+  )
+  params[order(match(firstnames, fnames))]
+}
 
-  lapply(par, function(t) {
+r6_tags_to_params <- function(tags) {
+  lapply(tags, function(t) {
     list(
       name = gsub(",", ", ", t$val$name),
       description = t$val$description
     )
   })
 }
 
+r6_param_names <- function(params) {
+  if (length(params) == 0) {
+    return(character())
+  }
+  trimws(unlist(strsplit(map_chr(params, \(x) x$name), ",")))
+}
+
 r6_method_name <- function(class, method) {
   paste0(class, "$", ifelse(method == "initialize", "new", method))
 }