[SOLVED] Documenting a package that defines a function with the same name

Documenting a package that defines a function with the same name

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...

Solution

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.