Documenting a package that defines a function with the same name

Question

I am writing a package named foo that defines an S3 class named foo with various S3 methods. I have written a constructor function foo() that returns a foo object. It seemed practical to name the class after the package, and the function after the class, and I hoped that:

• package?foo would bring up the package help page.
• ?foo and ?foo::foo would bring up the function help page.

But what happens is that:

• Both package?foo and ?foo bring up the package help page.
• Only ?foo::foo brings up the function help page.

Is there a way to give a package and a function the same name that produces my desired behaviour?

Currently I have a file foo_package.R like this:

#' The foo package
#' 
#' A very useful package.
#' 
#' @docType package
#' @name foo
NULL

and a file foo.R like this:

#' The foo function
#' 
#' A very useful function.
#' 
#' @param x A data frame.
#' @return A foo object.
#' @export
foo <- function(x) {
  structure(x, class = c("foo", "data.frame"))
}

Any hints are appreciated...

Answer 1

Following the second link in @MrFlick's comment, which points to the text under "Packages" in vignette("rd"), I was able to get the expected behaviour.

foo.R is unchanged, but foo-package.R now reads:

#' The foo package
#' 
#' A very useful package.
#' 
#' @docType package
#' @keywords internal
#' @aliases foo-package
"_PACKAGE"

Now, as desired:

• package?foo and ?"foo-package" bring up the package help.
• ?foo and ?foo::foo bring up the function help.