More careful ordering for @family tag (#1563)

NEWS.md

@@ -62,6 +62,8 @@
 
 * `@inherit` can now also inherit from `@format` (#1293). 
 
+* `@family` lists are now ordered more carefully, "foo1" comes after "foo" (#1563, @krlmlr).
+
 # roxygen2 7.2.3
 
 * roxygen2 now supports HTML blocks in markdown. They are only included

R/rd-family.R

@@ -51,12 +51,15 @@ topics_process_family <- function(topics, env) {
       if (length(others) < 1)
         next
 
-      by_file <- map_chr(aliases[others], function(x) {
+      other_aliases <- aliases[others]
+      other_aliases_order <- map_chr(other_aliases, function(x) escape(x[1]))
+
+      by_file <- map_chr(other_aliases[order_c(other_aliases_order)], function(x) {
         obj <- find_object(x[1], env)
         suffix <- if (is.function(obj$value)) "()" else ""
         paste0("\\code{\\link{", escape(x[1]), "}", suffix, "}")
       })
-      links <- paste(sort_c(by_file), collapse = ",\n")
+      links <- paste(by_file, collapse = ",\n")
       seealso <- topics_process_family_prefix(family)
 
       topic$add(rd_section("seealso", paste0(seealso, "\n", links)))

R/util-locale.R

@@ -11,4 +11,10 @@ with_collate <- function(locale, code) {
   force(code)
 }
 
-sort_c <- function(x, ...) with_collate("C", sort(x, ...))
+sort_c <- function(x, ...) {
+  with_collate("C", sort(x, ...))
+}
+
+order_c <- function(x, ...) {
+  with_collate("C", order(x, ...))
+}

tests/testthat/_snaps/rd-family.md

@@ -0,0 +1,86 @@
+# careful ordering
+
+    Code
+      out
+    Output
+      $foo1.Rd
+      % Generated by roxygen2: do not edit by hand
+      % Please edit documentation in ./<text>
+      \name{foo1}
+      \alias{foo1}
+      \title{foo1}
+      \usage{
+      foo1()
+      }
+      \description{
+      foo1
+      }
+      \seealso{
+      Other a: 
+      \code{\link{Foo3}()},
+      \code{\link{foo}()},
+      \code{\link{foo2}()}
+      }
+      \concept{a}
+      
+      $foo2.Rd
+      % Generated by roxygen2: do not edit by hand
+      % Please edit documentation in ./<text>
+      \name{foo2}
+      \alias{foo2}
+      \title{foo2}
+      \usage{
+      foo2()
+      }
+      \description{
+      foo2
+      }
+      \seealso{
+      Other a: 
+      \code{\link{Foo3}()},
+      \code{\link{foo}()},
+      \code{\link{foo1}()}
+      }
+      \concept{a}
+      
+      $Foo3.Rd
+      % Generated by roxygen2: do not edit by hand
+      % Please edit documentation in ./<text>
+      \name{Foo3}
+      \alias{Foo3}
+      \title{Foo3}
+      \usage{
+      Foo3()
+      }
+      \description{
+      Foo3
+      }
+      \seealso{
+      Other a: 
+      \code{\link{foo}()},
+      \code{\link{foo1}()},
+      \code{\link{foo2}()}
+      }
+      \concept{a}
+      
+      $foo.Rd
+      % Generated by roxygen2: do not edit by hand
+      % Please edit documentation in ./<text>
+      \name{foo}
+      \alias{foo}
+      \title{foo}
+      \usage{
+      foo()
+      }
+      \description{
+      foo
+      }
+      \seealso{
+      Other a: 
+      \code{\link{Foo3}()},
+      \code{\link{foo1}()},
+      \code{\link{foo2}()}
+      }
+      \concept{a}
+      
+

tests/testthat/test-rd-family.R

@@ -123,3 +123,27 @@ test_that("custom family prefixes can be set", {
 
   expect_match(out$get_value("seealso"), "^Custom prefix:")
 })
+
+test_that("careful ordering", {
+  out <- roc_proc_text(rd_roclet(), "
+    #' foo1
+    #' @family a
+    foo1 <- function() {}
+
+    #' foo2
+    #' @family a
+    foo2 <- function() {}
+
+    #' Foo3
+    #' @family a
+    Foo3 <- function() {}
+
+    #' foo
+    #' @family a
+    foo <- function() {}
+  ")
+
+  expect_snapshot({
+    out
+  })
+})