Anchor is to file name instead of an alias defined on the file

[llrs]

I was checking one package I'm working on and it reported a note:

checking Rd cross-references ... NOTE
  Non-topic package-anchored link(s) in Rd file 'bioc_cran_archived.Rd':
    ‘[tools:CRANtools]{tools::CRAN_package_db()}’
  
  Non-topic package-anchored link(s) in Rd file 'cran_doom.Rd':
    ‘[tools:CRANtools]{tools::CRAN_package_db()}’
  
  See section 'Cross-references' in the 'Writing R Extensions' manual.

The help file is generated with something like this:

library("roxygen2")
out <- roc_proc_text(rd_roclet(), "
  #' Playing with links
  #'
  #' @seealso [tools::CRAN_package_db()]
  #' @md
  null <- function () NULL
")[[1]]

out
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \name{null}
#> \alias{null}
#> \title{Playing with links}
#> \usage{
#> null()
#> }
#> \description{
#> Playing with links
#> }
#> \seealso{
#> \code{\link[tools:CRANtools]{tools::CRAN_package_db()}}
#> }

rdfile <- tempfile()
cat(out$format(), file = rdfile)
tools::checkRd(rdfile)
help("CRANtools", package = "tools")
#> No documentation for 'CRANtools' in specified packages and libraries:
#> you could try '??CRANtools'

^{Created on 2025-04-19 with reprex v2.1.1}

The file in question has several alias but the name (CRANtools) is not one of them: CRAN_package_db, CRAN_check_results, CRAN_check_details, CRAN_check_issues, summarize_CRAN_check_status, R_CRAN_WEB, R_CRAN_SRC, CRAN_current_db, CRAN_aliases_db, CRAN_rdxrefs_db, CRAN_archive_db, CRAN_authors_db.

It would be great if it generated a cross reference with the same anchor as the function being used.

[LiNk-NY]

I am also seeing this with S4 class documentation (which is stated as not done yet, in https://roxygen2.r-lib.org/articles/markdown.html)

To clarify, a topic resolves to the documentation file name rather than using the topic. For example,
[`ExpressionSet`][Biobase::ExpressionSet-class] returns
\code{\link[Biobase:class.ExpressionSet]{ExpressionSet}} instead of
\code{\link[Biobase:ExpressionSet-class]{ExpressionSet}}

This issue results in a NOTE in R 4.5.0 patched:

* checking Rd cross-references ... NOTE
Non-topic package-anchored link(s) in Rd file 'class.Rd':
  ‘[Biobase:class.ExpressionSet]{Biobase::ExpressionSet}’

The workaround is to use \code{\link[Biobase:ExpressionSet-class]{ExpressionSet}} directly in the documentation.

[llrs]

I explored this based on private correspondence with Kurt Hornik. To retrieve the alias use internal R functions (show in examples of Rd_db) or parse the object (or the resulting character):

db <- tools::Rd_db("roxygen2")
aliases <- lapply(db, function(x) {
    rd <- as.character(x)
    position_aliases <- which(rd == "\\alias") + 2
    position_keyword <- which(rd == "\\keyword") + 2
    internal <- any(rd[position_keyword] == "internal")
    if (internal) {
        return(NULL)
    }
    aliases <- rd[position_aliases]
    aliases[!startsWith(aliases, "@")]
})

The only tricky thing could be how to handle internal documentation. Currently help opens them, for example help("tag_parsers", "roxygen2") but users probably shouldn't link to it or at least without a warning (and roxygen2-package.Rd is also marked as internal and currently misses the \docType tag):

library("roxygen2")
roc_proc_text(rd_roclet(), r"{(
  #' @rdname margins
  #' @name margins
  #' @aliases margins-package
  #' @title Marginal Effects Estimation
  "_PACKAGES"
)}")[[1]]
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \name{margins}
#> \alias{margins}
#> \alias{margins-package}
#> \title{Marginal Effects Estimation}
#> \description{
#> Marginal Effects Estimation
#> }

^{Created on 2025-05-07 with reprex v2.1.1}

[llrs-roche]

I also found this issue when inheriting parameters or Dots.
For example:

#' inheritDotParams gtsummary::add_p.tbl_summary 
Error: 'add_p.tbl_summary' is not an exported object from 'namespace:gtsummary'

Fails to find the parameters as the generic exported (gtsummary::add_p) method doesn't have many of the documented parameters add_p.tbl_summary has but as the object is not exported it fails to find the parameters...