How do I use roxygen to document a R package that includes a function with the same name?

Question

I'm learning to use roxygen. I see that the rd vignette advocates using "_PACKAGE" to indicate that I'm creating package documentation, and says "This also works if there’s already a function called pkgname()."

I've also seen the R packages book approach of using

NULL

with @docType and @name specified, but when I attempt to make a toy example with either approach, it doesn't work as I expect.

As a toy example, I'd like to make a "hello" package that includes a "hello()" function.

I expect to get documentation about my hello package with

?hello

or perhaps something like

package?hello

and I expect to get documentation about the included hello function with

?hello()

Where am I going wrong? - implementation with roxygen, the way I'm attempting to query the documentation, incorrect expectations, or something else?

I've already looked at questions about package documentation and function documentation, but things remain unclear to me.

Here's some details about my toy example:

hello/DESCRIPTION file:

Package: hello
Type: Package
Title: A mostly empty package
Version: 0.1
Date: 2016-06-21
Authors@R: person("Some", "Person", email = "[email protected]", role = c("aut", "cre"))
Description: More about what it does (maybe more than one line)
License: MIT
LazyData: TRUE
RoxygenNote: 5.0.1.9000

hello/R/hello.R

#' hello
#'
#' This is a mostly empty package to learn roxygen documentation.
#'
#' Hello allows me to learn how to write documentation in comment blocks
#' co-located with code.
#' @docType package
#' @name hello
"_PACKAGE"

#' hello
#'
#' This function returns "Hello, world!".
#' @export
#' @examples
#' hello()

hello <- function() {
  print("Hello, world!")
}

With this, after I run document(), hello/man/hello.Rd is generated. It contains a combination of the descriptions I've written for the hello package and the hello() function. ?hello and ?hello() both return that .Rd file.

Here's what the .Rd looks like:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hello.R
\docType{package}
\name{hello}
\alias{hello}
\alias{hello-package}
\title{hello}
\usage{
hello()
}
\description{
This is a mostly empty package to learn roxygen documentation.

This function returns "Hello, world!".
}
\details{
Hello allows me to learn how to write documentation in comment blocks
co-located with code.
}
\examples{
hello()
}

Answer 1

via @hadley, "don’t use @ name hello. That overrides default naming" and "sometimes you need to restart R because there’s something buggy with devtools and dev docs"

So, if I change my hello.R file to this:

#' hello
#'
#' This is a mostly empty package to learn roxygen documentation.
#'
#' Hello allows me to learn how to write documentation in comment blocks
#' co-located with code.
"_PACKAGE"

#' hello
#'
#' This function returns "Hello, world!".
#' @export
#' @examples
#' hello()

hello <- function() {
  print("Hello, world!")
}

then document() makes hello-package.Rd and hello.Rd files. After I load library(hello), then package?hello provides package documentation, and ?hello provides function documentation, as I was shooting for!

Thank you once again, @hadley!