Mimic R-4 documentation for Usage (r-lib#2189)

Fixes r-lib#2187

Co-authored-by: Hadley Wickham <[email protected]>

NEWS.md

@@ -1,5 +1,6 @@
 # pkgdown (development version)
 
+* `build_reference()` matches usage for S3 and S4 methods to the style used by R 4.0.0 and later (#2187).
 * `<source>` tags now have their `srcref` attributes tweaked in the same way that the `src` attributes of `<img>` tags are (#2402).
 * New translation for "Search site", the label applied to the search box for screenreaders. This was previously incorrectly labelled as "Toggle navigation" (#2320).
 * You can now choose where the search box is placed with the "search" navbar component. This has been documented for a very long time, but as far as I can tell, never worked (#2320). If you have made your own template with a custom `navbar`, you will need to remove the `<form>` with `role="search"` to avoid getting two search boxes.

R/rd-html.R

@@ -204,10 +204,14 @@ as_html.tag_S4method <- function(x, ...) method_usage(x, "S4")
 method_usage <- function(x, type) {
   fun <- as_html(x[[1]])
   class <- as_html(x[[2]])
-  paste0(
-    sprintf(tr_("# %s method for %s"), type, class),
-    "\n", fun
-  )
+
+  if (x[[2]] == "default") {
+    method <- sprintf(tr_("# Default %s method"), type)
+  } else {
+    method <- sprintf(tr_("# %s method for class '%s'"), type, class)
+  }
+
+  paste0(method, "\n", fun)
 }
 
 # Conditionals and Sexprs ----------------------------------------------------

po/R-pkgdown.pot

@@ -258,8 +258,12 @@ msgstr ""
 msgid "Value"
 msgstr ""
 
-#: rd-html.R:208
-msgid "# %s method for %s"
+#: rd-html.R:209
+msgid "# Default %s method"
+msgstr ""
+
+#: rd-html.R:211
+msgid "# %s method for class '%s'"
 msgstr ""
 
 #: render.R:90

tests/testthat/test-rd-html.R

@@ -402,34 +402,42 @@ test_that("spaces are preserved in preformatted blocks", {
 
 test_that("S4 methods gets comment", {
   out <- rd2html("\\S4method{fun}{class}(x, y)")
-  expect_equal(out[1], "# S4 method for class")
+  expect_equal(out[1], "# S4 method for class 'class'")
   expect_equal(out[2], "fun(x, y)")
 })
 
 test_that("S3 methods gets comment", {
   out <- rd2html("\\S3method{fun}{class}(x, y)")
-  expect_equal(out[1], "# S3 method for class")
+  expect_equal(out[1], "# S3 method for class 'class'")
   expect_equal(out[2], "fun(x, y)")
 
   out <- rd2html("\\method{fun}{class}(x, y)")
-  expect_equal(out[1], "# S3 method for class")
+  expect_equal(out[1], "# S3 method for class 'class'")
   expect_equal(out[2], "fun(x, y)")
 })
 
 test_that("Methods for class function work", {
   out <- rd2html("\\S3method{fun}{function}(x, y)")
-  expect_equal(out[1], "# S3 method for function")
+  expect_equal(out[1], "# S3 method for class 'function'")
   expect_equal(out[2], "fun(x, y)")
 
   out <- rd2html("\\method{fun}{function}(x, y)")
-  expect_equal(out[1], "# S3 method for function")
+  expect_equal(out[1], "# S3 method for class 'function'")
   expect_equal(out[2], "fun(x, y)")
 
   out <- rd2html("\\S4method{fun}{function,function}(x, y)")
-  expect_equal(out[1], "# S4 method for function,function")
+  expect_equal(out[1], "# S4 method for class 'function,function'")
   expect_equal(out[2], "fun(x, y)")
 })
 
+test_that("default methods get custom text", {
+  out <- rd2html("\\S3method{fun}{default}(x, y)")
+  expect_equal(out[1], "# Default S3 method")
+
+  out <- rd2html("\\S4method{fun}{default}(x, y)")
+  expect_equal(out[1], "# Default S4 method")
+})
+
 test_that("eqn", {
   out <- rd2html(" \\eqn{\\alpha}{alpha}")
   expect_equal(out, "\\(\\alpha\\)")