Skip to content

Commit 5753cd8

Browse files
hadleyhadley
authored
Tweak R6 usage (#1815)
Consistently refer to methods in the same way in every location. Fixes #1258
1 parent 5ffcdbe commit 5753cd8

10 files changed

Lines changed: 52 additions & 60 deletions

‎NEWS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
* `@examplesIf` now warns when there is no example code after the condition (#1695).
44
* `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.
55
* R6 improvements:
6+
* 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).
67
* `@returns` now works as a method-level tag in R6 classes, just like `@return` (#1148).
78
* The "Super classes" section now omits the `pkg::` prefix for parent classes from the same package, making the inheritance chain easier to read (#1567).
89
* R6 classes with only active bindings and `cloneable = FALSE` no longer error during documentation (#1610).

‎R/rd-r6-methods-self.R‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
rd_r6_method <- function(
22
name,
33
class,
4-
alias,
54
formals,
65
description = character(),
76
details = character(),
@@ -13,7 +12,6 @@ rd_r6_method <- function(
1312
list(
1413
name = name,
1514
class = class,
16-
alias = alias,
1715
formals = formals,
1816
description = description,
1917
details = details,
@@ -27,7 +25,6 @@ rd_r6_method <- function(
2725

2826
#' @export
2927
format.rd_r6_method <- function(x, ...) {
30-
nm <- r6_show_name(x$name)
3128
lines <- character()
3229
push <- function(...) lines <<- c(lines, ...)
3330
push_subsection <- function(title, ...) {
@@ -39,11 +36,14 @@ format.rd_r6_method <- function(x, ...) {
3936
}
4037

4138
# Anchor and heading
42-
id <- paste0("method-", x$class, "-", nm)
39+
call <- r6_method_name(x$class, x$name)
40+
41+
id <- paste0("method-", x$class, "-", x$name)
4342
push(rd_if_html("<hr>"))
4443
push(rd_if_html('<a id="', id, '"></a>'))
4544
push(rd_if_latex("\\hypertarget{", id, "}{}"))
46-
push(paste0("\\subsection{Method \\code{", nm, "()}}{"))
45+
46+
push(paste0("\\subsection{\\code{", call, "()}}{"))
4747

4848
# Description
4949
if (length(x$description) > 0) {
@@ -54,13 +54,12 @@ format.rd_r6_method <- function(x, ...) {
5454
}
5555

5656
# Usage
57-
usage_name <- paste0(x$alias, "$", nm)
58-
fake <- paste(rep("X", nchar(usage_name)), collapse = "")
57+
fake <- paste(rep("X", nchar(call)), collapse = "")
5958
usage <- format(function_usage(fake, x$formals))
6059
push_subsection(
6160
"Usage",
6261
rd_if_html('<div class="r">'),
63-
paste0("\\preformatted{", sub(paste0("^", fake), usage_name, usage), "}"),
62+
paste0("\\preformatted{", sub(paste0("^", fake), call, usage), "}"),
6463
rd_if_html("</div>")
6564
)
6665

@@ -108,7 +107,7 @@ format.rd_r6_method <- function(x, ...) {
108107
lines
109108
}
110109

111-
r6_method_from_row <- function(method, alias, block) {
110+
r6_method_from_row <- function(method, block) {
112111
tags <- method$tags[[1]]
113112

114113
desc_tags <- keep(tags, \(t) t$tag == "description")
@@ -131,7 +130,6 @@ r6_method_from_row <- function(method, alias, block) {
131130
rd_r6_method(
132131
name = method$name,
133132
class = method$class,
134-
alias = alias,
135133
formals = method$formals[[1]],
136134
description = description,
137135
details = details,
@@ -222,9 +220,8 @@ r6_resolve_params <- function(method, block) {
222220
})
223221
}
224222

225-
# vectorized
226-
r6_show_name <- function(names) {
227-
ifelse(names == "initialize", "new", names)
223+
r6_method_name <- function(class, method) {
224+
paste0(class, "$", ifelse(method == "initialize", "new", method))
228225
}
229226

230227
rd_if_html <- function(...) {

‎R/rd-r6-methods.R‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ format.rd_r6_methods <- function(x, ...) {
1414
lines <- character()
1515
push <- function(...) lines <<- c(lines, ...)
1616

17-
nms <- r6_show_name(map_chr(x$self, \(m) m$name))
17+
nms <- map_chr(x$self, \(m) m$name)
1818
classes <- map_chr(x$self, \(m) m$class)
1919
dest <- sprintf("method-%s-%s", classes, nms)
20-
code <- sprintf("\\code{%s$%s()}", x$alias, nms)
20+
code <- sprintf("\\code{%s()}", r6_method_name(classes, nms))
2121

2222
push("\\section{Methods}{")
2323
push(
@@ -74,7 +74,7 @@ r6_extract_methods <- function(r6data, alias, block) {
7474

7575
self_methods <- lapply(
7676
seq_len(nrow(methods_df)),
77-
function(i) r6_method_from_row(methods_df[i, ], alias, block)
77+
function(i) r6_method_from_row(methods_df[i, ], block)
7878
)
7979
inherited <- r6_extract_inherited_methods(r6data)
8080
rd_r6_methods(alias, self = self_methods, inherited = inherited)
@@ -144,10 +144,9 @@ r6_all_examples <- function(methods) {
144144
if (length(method$examples) == 0) {
145145
return()
146146
}
147-
name <- paste0(methods$alias, "$", r6_show_name(method$name))
148147
c(
149148
"\n## ------------------------------------------------",
150-
paste0("## Method `", name, "`"),
149+
paste0("## Method `", r6_method_name(method$class, method$name), "()`"),
151150
"## ------------------------------------------------\n",
152151
paste(method$examples, collapse = "\n")
153152
)

‎man/RoxyTopic.Rd‎

Lines changed: 12 additions & 12 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
\if{html}{\out{<hr>}}
5151
\if{html}{\out{<a id="method-C2-meth1"></a>}}
5252
\if{latex}{\out{\hypertarget{method-C2-meth1}{}}}
53-
\subsection{Method \code{meth1()}}{
53+
\subsection{\code{C2$meth1()}}{
5454
method1
5555
\subsection{Usage}{
5656
\if{html}{\out{<div class="r">}}
@@ -84,7 +84,7 @@
8484
\if{html}{\out{<hr>}}
8585
\if{html}{\out{<a id="method-B-shared"></a>}}
8686
\if{latex}{\out{\hypertarget{method-B-shared}{}}}
87-
\subsection{Method \code{shared()}}{
87+
\subsection{\code{B$shared()}}{
8888
Method from B.
8989
\subsection{Usage}{
9090
\if{html}{\out{<div class="r">}}
@@ -96,7 +96,7 @@
9696
\if{html}{\out{<hr>}}
9797
\if{html}{\out{<a id="method-B-clone"></a>}}
9898
\if{latex}{\out{\hypertarget{method-B-clone}{}}}
99-
\subsection{Method \code{clone()}}{
99+
\subsection{\code{B$clone()}}{
100100
The objects of this class are cloneable with this method.
101101
\subsection{Usage}{
102102
\if{html}{\out{<div class="r">}}
@@ -129,7 +129,7 @@
129129
\if{html}{\out{<hr>}}
130130
\if{html}{\out{<a id="method-C-meth"></a>}}
131131
\if{latex}{\out{\hypertarget{method-C-meth}{}}}
132-
\subsection{Method \code{meth()}}{
132+
\subsection{\code{C$meth()}}{
133133
Method description.
134134
135135
\subsection{Description section}{

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
\if{html}{\out{<hr>}}
3232
\if{html}{\out{<a id="method-Person-greet"></a>}}
3333
\if{latex}{\out{\hypertarget{method-Person-greet}{}}}
34-
\subsection{Method \code{greet()}}{
34+
\subsection{\code{Person$greet()}}{
3535
Say hello.
3636
\subsection{Usage}{
3737
\if{html}{\out{<div class="r">}}
@@ -56,9 +56,9 @@
5656
cat(format(method), sep = "\n")
5757
Output
5858
\if{html}{\out{<hr>}}
59-
\if{html}{\out{<a id="method-Foo-new"></a>}}
60-
\if{latex}{\out{\hypertarget{method-Foo-new}{}}}
61-
\subsection{Method \code{new()}}{
59+
\if{html}{\out{<a id="method-Foo-initialize"></a>}}
60+
\if{latex}{\out{\hypertarget{method-Foo-initialize}{}}}
61+
\subsection{\code{Foo$new()}}{
6262
Create object.
6363
\subsection{Usage}{
6464
\if{html}{\out{<div class="r">}}
@@ -76,7 +76,7 @@
7676
\if{html}{\out{<hr>}}
7777
\if{html}{\out{<a id="method-Job-run"></a>}}
7878
\if{latex}{\out{\hypertarget{method-Job-run}{}}}
79-
\subsection{Method \code{run()}}{
79+
\subsection{\code{Job$run()}}{
8080
Run the job.
8181
\subsection{Usage}{
8282
\if{html}{\out{<div class="r">}}
@@ -109,7 +109,7 @@
109109
\if{html}{\out{<hr>}}
110110
\if{html}{\out{<a id="method-Job-run"></a>}}
111111
\if{latex}{\out{\hypertarget{method-Job-run}{}}}
112-
\subsection{Method \code{run()}}{
112+
\subsection{\code{Job$run()}}{
113113
Run.
114114
\subsection{Usage}{
115115
\if{html}{\out{<div class="r">}}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
\if{html}{\out{<hr>}}
1313
\if{html}{\out{<a id="method-Foo-run"></a>}}
1414
\if{latex}{\out{\hypertarget{method-Foo-run}{}}}
15-
\subsection{Method \code{run()}}{
15+
\subsection{\code{Foo$run()}}{
1616
Run it.
1717
\subsection{Usage}{
1818
\if{html}{\out{<div class="r">}}
@@ -30,13 +30,13 @@
3030
Output
3131
3232
## ------------------------------------------------
33-
## Method `C$greet`
33+
## Method `C$greet()`
3434
## ------------------------------------------------
3535
3636
c$greet()
3737
3838
## ------------------------------------------------
39-
## Method `C$stop`
39+
## Method `C$stop()`
4040
## ------------------------------------------------
4141
4242
c$stop()

0 commit comments

Comments
 (0)