Consistently qualify [base] in Rd links

[MichaelChirico]

Let's specify destinations of non-local links. That won't give us R CMD check problems, but it should help the resolver.

  \code{\link[base]{options}},
  \code{\link[base]{getOption}},

Originally posted by @aitap in #7075 (comment)

This was applied in #7075, but it's not consistent in our code base:

data.table/man/data.table.Rd

Line 88 in a5eac7d

The expression \code{.()} is a \emph{shorthand} alias to \code{list()}; they both mean the same. (An exception is made for the use of \code{.()} within a call to \code{\link{bquote}}, where \code{.()} is left unchanged.)

Let's do so consistently, including a linter to prevent regression.

[jangorecki]

Let's do so consistently, including a linter to prevent regression.

+1
But let's not make it top priority stuff that will cause new git conflicts. Adding it later on will not make any harm...

[MichaelChirico]

To facilitate this type of discussion, I made LLM write a script (happily it worked copy+paste, but I tweaked it a bit anyway):

https://gist.github.com/MichaelChirico/64e981b4359a36d2279bf55c39c7d3dd

Here are the non-froll non-draft PRs that touch any existing Rd file

#6899, #6879, #6624, #6360, #6136, #5168, #4978, #4868, #3093

They touch files:

all.equal.data.table.Rd, data.table.Rd, groupingsets.Rd, IDateTime.Rd, last.Rd, na.omit.data.table.Rd, setDT.Rd

froll drafts all only touch man/froll.Rd, except #5441, which appears to have an ongoing merge conflict/rebase issue where unrelated edits are showing up in other man/ files.

extant_rd = list.files('man')
pr_files[
  !is_draft & !grepl("froll", labels) & basename(filename) %in% extant_rd,
  paste0("#", unique(pr_number), collapse = ", ")
]

I think it's fine to file a PR for this issue now, if the PR author agrees to also resolve any conflicts with the listed PRs afterwards, should any arise.

[jangorecki]

If it is just a few PRs then we could alternatively try to merge or close them before. That will end up to be less work in total, than the other way around.

[aitap]

It's not necessary to spell out \link[foo:bar]{bar} instead of \link[foo]{bar}, tools:::get_link resolves them the same way, but it shouldn't hurt too much either.

This issue isn't of high priority because even unqualified links to base topics should never fail to resolve, people usually don't create conflicts with base topics, and R CMD check only gives a NOTE about unqualified non-(base or local) links, but it is useful in case a topic conflict does occur.

[aitap]

To quantify the problem:

# list of topics documented on CRAN
tools::CRAN_aliases_db() -> cran_aliases
# (takes a long time)
cran_aliases |> names() |> lapply(\(pkg)
 cran_aliases[[pkg]] |> names() |> lapply(\(file)
  data.table(alias = cran_aliases[[pkg]][[file]], file = file, pkg = pkg)
  )
 ) |> unlist(FALSE) |> rbindlist() -> cran_alias_db

# list of documented topics in base packages (destinations for \link{foo})
tools::base_aliases_db() |> unlist(use.names=FALSE) |> unique() -> base_aliases
length(base_aliases) # ⇒ [1] 4696

# links from the data.table help pages
tools::CRAN_rdxrefs_db()$data.table |> as.data.table() -> dt_xrefs

# Any unqualified links from data.table to base topics intersecting with CRAN?
dt_xrefs[
 # Any unqualified links from data.table...
 !nzchar(Anchor), -'Anchor'
][
 # ...to base topics....
 J(Target = base_aliases), on = .(Target), nomatch = NULL
][
 # ...intersecting with aliases from CRAN, not in data.table itself?
 cran_alias_db[pkg != 'data.table'], on = .(Target = alias), nomatch = NULL
][
 , .(Source = paste(unique(Source), collapse = ', '), dest = paste(pkg, file, sep = ':', collapse = ', ')), by = .(Target)
] -> potential_conflicts
potential_conflicts[,-'dest'] # the last column can be really long

           Target                                   Source
           <char>                                   <char>
 1:        format                             as.matrix.Rd
 2:   object.size                                tables.Rd
 3:        unique duplicated.Rd, fdroplevels.Rd, setops.Rd
 4:         merge                                 merge.Rd
 5:    data.frame                  data.table.Rd, setDT.Rd
 6:          head                                  last.Rd
 7:          tail                                  last.Rd
 8:    duplicated duplicated.Rd, fdroplevels.Rd, setops.Rd
 9:          %in%                               chmatch.Rd
10:     as.matrix                             as.matrix.Rd
11:     as.vector                             as.matrix.Rd
12:         round                             IDateTime.Rd
13:       na.omit                            data.table.Rd
14: print.default                      print.data.table.Rd
15: download.file                                 fread.Rd
16:    is.numeric                            data.table.Rd
17:     all.equal                            duplicated.Rd
18:       POSIXct                                 fread.Rd
19:      patterns                       melt.data.table.Rd
20:         array                             as.matrix.Rd
21:            ls                                tables.Rd
22:       as.Date                             IDateTime.Rd
23:          grep                              patterns.Rd
24:      strptime                             IDateTime.Rd
25:       strtrim                      print.data.table.Rd

This is only a minor problem when using the dynamic help server (help.start()). With R CMD INSTALL --html, the links will be forced to resolve to the base and recommended packages before they can be resolved to CRAN packages.