Tweak R6 usage

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:
+  * R6 method usage now shows `ClassName$new(args)` for constructors and `obj$method(args)` for other methods, making it clearer how each method is actually called (#1026).
   * `@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).

R/rd-r6-methods-self.R

@@ -1,7 +1,6 @@
 rd_r6_method <- function(
   name,
   class,
-  alias,
   formals,
   description = character(),
   details = character(),
@@ -13,7 +12,6 @@ rd_r6_method <- function(
     list(
       name = name,
       class = class,
-      alias = alias,
       formals = formals,
       description = description,
       details = details,
@@ -27,7 +25,6 @@ rd_r6_method <- function(
 
 #' @export
 format.rd_r6_method <- function(x, ...) {
-  nm <- r6_show_name(x$name)
   lines <- character()
   push <- function(...) lines <<- c(lines, ...)
   push_subsection <- function(title, ...) {
@@ -39,11 +36,14 @@ format.rd_r6_method <- function(x, ...) {
   }
 
   # Anchor and heading
-  id <- paste0("method-", x$class, "-", nm)
+  call <- r6_method_name(x$class, x$name)
+
+  id <- paste0("method-", x$class, "-", x$name)
   push(rd_if_html("<hr>"))
   push(rd_if_html('<a id="', id, '"></a>'))
   push(rd_if_latex("\\hypertarget{", id, "}{}"))
-  push(paste0("\\subsection{Method \\code{", nm, "()}}{"))
+
+  push(paste0("\\subsection{\\code{", call, "()}}{"))
 
   # Description
   if (length(x$description) > 0) {
@@ -54,13 +54,12 @@ format.rd_r6_method <- function(x, ...) {
   }
 
   # Usage
-  usage_name <- paste0(x$alias, "$", nm)
-  fake <- paste(rep("X", nchar(usage_name)), collapse = "")
+  fake <- paste(rep("X", nchar(call)), collapse = "")
   usage <- format(function_usage(fake, x$formals))
   push_subsection(
     "Usage",
     rd_if_html('<div class="r">'),
-    paste0("\\preformatted{", sub(paste0("^", fake), usage_name, usage), "}"),
+    paste0("\\preformatted{", sub(paste0("^", fake), call, usage), "}"),
     rd_if_html("</div>")
   )
 
@@ -108,7 +107,7 @@ format.rd_r6_method <- function(x, ...) {
   lines
 }
 
-r6_method_from_row <- function(method, alias, block) {
+r6_method_from_row <- function(method, block) {
   tags <- method$tags[[1]]
 
   desc_tags <- keep(tags, \(t) t$tag == "description")
@@ -131,7 +130,6 @@ r6_method_from_row <- function(method, alias, block) {
   rd_r6_method(
     name = method$name,
     class = method$class,
-    alias = alias,
     formals = method$formals[[1]],
     description = description,
     details = details,
@@ -222,9 +220,8 @@ r6_resolve_params <- function(method, block) {
   })
 }
 
-# vectorized
-r6_show_name <- function(names) {
-  ifelse(names == "initialize", "new", names)
+r6_method_name <- function(class, method) {
+  paste0(class, "$", ifelse(method == "initialize", "new", method))
 }
 
 rd_if_html <- function(...) {

R/rd-r6-methods.R

@@ -14,10 +14,10 @@ format.rd_r6_methods <- function(x, ...) {
   lines <- character()
   push <- function(...) lines <<- c(lines, ...)
 
-  nms <- r6_show_name(map_chr(x$self, \(m) m$name))
+  nms <- map_chr(x$self, \(m) m$name)
   classes <- map_chr(x$self, \(m) m$class)
   dest <- sprintf("method-%s-%s", classes, nms)
-  code <- sprintf("\\code{%s$%s()}", x$alias, nms)
+  code <- sprintf("\\code{%s()}", r6_method_name(classes, nms))
 
   push("\\section{Methods}{")
   push(
@@ -74,7 +74,7 @@ r6_extract_methods <- function(r6data, alias, block) {
 
   self_methods <- lapply(
     seq_len(nrow(methods_df)),
-    function(i) r6_method_from_row(methods_df[i, ], alias, block)
+    function(i) r6_method_from_row(methods_df[i, ], block)
   )
   inherited <- r6_extract_inherited_methods(r6data)
   rd_r6_methods(alias, self = self_methods, inherited = inherited)
@@ -144,10 +144,9 @@ r6_all_examples <- function(methods) {
     if (length(method$examples) == 0) {
       return()
     }
-    name <- paste0(methods$alias, "$", r6_show_name(method$name))
     c(
       "\n## ------------------------------------------------",
-      paste0("## Method `", name, "`"),
+      paste0("## Method `", r6_method_name(method$class, method$name), "()`"),
       "## ------------------------------------------------\n",
       paste(method$examples, collapse = "\n")
     )

tests/testthat/_snaps/rd-r6-class.md

@@ -50,7 +50,7 @@
       \if{html}{\out{<hr>}}
       \if{html}{\out{<a id="method-C2-meth1"></a>}}
       \if{latex}{\out{\hypertarget{method-C2-meth1}{}}}
-      \subsection{Method \code{meth1()}}{
+      \subsection{\code{C2$meth1()}}{
       method1
       \subsection{Usage}{
       \if{html}{\out{<div class="r">}}
@@ -84,7 +84,7 @@
       \if{html}{\out{<hr>}}
       \if{html}{\out{<a id="method-B-shared"></a>}}
       \if{latex}{\out{\hypertarget{method-B-shared}{}}}
-      \subsection{Method \code{shared()}}{
+      \subsection{\code{B$shared()}}{
       Method from B.
       \subsection{Usage}{
       \if{html}{\out{<div class="r">}}
@@ -96,7 +96,7 @@
       \if{html}{\out{<hr>}}
       \if{html}{\out{<a id="method-B-clone"></a>}}
       \if{latex}{\out{\hypertarget{method-B-clone}{}}}
-      \subsection{Method \code{clone()}}{
+      \subsection{\code{B$clone()}}{
       The objects of this class are cloneable with this method.
       \subsection{Usage}{
       \if{html}{\out{<div class="r">}}
@@ -129,7 +129,7 @@
       \if{html}{\out{<hr>}}
       \if{html}{\out{<a id="method-C-meth"></a>}}
       \if{latex}{\out{\hypertarget{method-C-meth}{}}}
-      \subsection{Method \code{meth()}}{
+      \subsection{\code{C$meth()}}{
       Method description.
 
       \subsection{Description section}{

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

@@ -31,7 +31,7 @@
       \if{html}{\out{<hr>}}
       \if{html}{\out{<a id="method-Person-greet"></a>}}
       \if{latex}{\out{\hypertarget{method-Person-greet}{}}}
-      \subsection{Method \code{greet()}}{
+      \subsection{\code{Person$greet()}}{
       Say hello.
       \subsection{Usage}{
       \if{html}{\out{<div class="r">}}
@@ -56,9 +56,9 @@
       cat(format(method), sep = "\n")
     Output
       \if{html}{\out{<hr>}}
-      \if{html}{\out{<a id="method-Foo-new"></a>}}
-      \if{latex}{\out{\hypertarget{method-Foo-new}{}}}
-      \subsection{Method \code{new()}}{
+      \if{html}{\out{<a id="method-Foo-initialize"></a>}}
+      \if{latex}{\out{\hypertarget{method-Foo-initialize}{}}}
+      \subsection{\code{Foo$new()}}{
       Create object.
       \subsection{Usage}{
       \if{html}{\out{<div class="r">}}
@@ -76,7 +76,7 @@
       \if{html}{\out{<hr>}}
       \if{html}{\out{<a id="method-Job-run"></a>}}
       \if{latex}{\out{\hypertarget{method-Job-run}{}}}
-      \subsection{Method \code{run()}}{
+      \subsection{\code{Job$run()}}{
       Run the job.
       \subsection{Usage}{
       \if{html}{\out{<div class="r">}}
@@ -109,7 +109,7 @@
       \if{html}{\out{<hr>}}
       \if{html}{\out{<a id="method-Job-run"></a>}}
       \if{latex}{\out{\hypertarget{method-Job-run}{}}}
-      \subsection{Method \code{run()}}{
+      \subsection{\code{Job$run()}}{
       Run.
       \subsection{Usage}{
       \if{html}{\out{<div class="r">}}

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

@@ -12,7 +12,7 @@
       \if{html}{\out{<hr>}}
       \if{html}{\out{<a id="method-Foo-run"></a>}}
       \if{latex}{\out{\hypertarget{method-Foo-run}{}}}
-      \subsection{Method \code{run()}}{
+      \subsection{\code{Foo$run()}}{
       Run it.
       \subsection{Usage}{
       \if{html}{\out{<div class="r">}}
@@ -30,13 +30,13 @@
     Output
 
       ## ------------------------------------------------
-      ## Method `C$greet`
+      ## Method `C$greet()`
       ## ------------------------------------------------
 
       c$greet()
 
       ## ------------------------------------------------
-      ## Method `C$stop`
+      ## Method `C$stop()`
       ## ------------------------------------------------
 
       c$stop()