When developing an R package where a primary function shares the exact same name as the package itself (for example, a function bla() inside a package named bla), you might encounter an unexpected quirk in your documentation: running ?bla displays a "Useful links" section under See Also that points to the URLs in your DESCRIPTION file.

This occurs even when you didn't explicitly add a @seealso tag to the function. If you want to keep your function reference clean and prevent roxygen2 from injecting package-level links into individual function docs, here is why it happens and how to resolve it.

Why Does 'Useful Links' Appear on Your Function?

By default, roxygen2 looks for a place to put package-level metadata—specifically the URL and BugReports fields defined in your DESCRIPTION file. Roxygen2 places these links inside an Rd block under \seealso on the package's primary documentation page.

When your package lacks a dedicated package-level documentation page (conventionally named pkgname-package), roxygen2 or R's help system matches the package name to the function Rd file named bla.Rd. Because the topic name matches the package name, roxygen2 treats your function documentation as the de facto package documentation page, automatically injecting the "Useful links" section.

Solution 1: Create a Dedicated Package Documentation File (Recommended)

The standard, CRAN-recommended way to resolve this collision is to provide an explicit package-level documentation file using roxygen2's _PACKAGE sentinel.

If you use usethis, you can generate this file automatically by running:

usethis::use_package_doc()

Alternatively, create a file named R/bla-package.R manually with the following content:

#' @keywords internal
"_PACKAGE"

## usethis namespace: start
## usethis namespace: end
NULL

After adding this file, regenerate your documentation:

roxygen2::roxygenize()
# or in devtools:
devtools::document()

How this fixes the problem:

  • Roxygen2 will now create a dedicated man/bla-package.Rd file.
  • The automatic "Useful links" section is attached exclusively to ?`bla-package`.
  • Your function's help page (?bla) will remain clean and contain only the documentation you explicitly defined.

Solution 2: Check for Overlapping Aliases

If you already have a _PACKAGE file or package documentation, verify that your function documentation does not inadvertently include aliases that trigger package-level matching. Inspect your function's roxygen header in R/bla.R:

#' My Main Function
#'
#' @param x An input vector
#' @aliases bla-package  # <-- REMOVE THIS IF PRESENT
#' @docType package      # <-- REMOVE THIS IF PRESENT
#' @export
bla <- function(x) {
  # ...
}

Ensure that neither @docType package nor @aliases <packagename>-package is attached to the function itself.

Should You Move the URL to the 'Description' Field?

In your DESCRIPTION file, keeping the formal URL: and BugReports: fields is a best practice—and often mandatory if you intend to publish on CRAN or Bioconductor. Moving the URL into free-form text in the Description: field is not recommended, as package indexes, CRAN checks, and tools like pkgdown rely on structured metadata fields.

Summary

You do not need to remove the URL tag from DESCRIPTION. The appearance of "Useful links" on your function documentation is simply roxygen2 falling back to the topic matching your package name. By separating the package-level help using usethis::use_package_doc() (or a manual "_PACKAGE" block), your function help page and package metadata will each have their own appropriate space.