How do I use roxygen to document a R package that includes a function with the same name?
<p>I'm learning to use roxygen. I see that the <a href="https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html#documenting-packages" rel="noreferrer">rd vignette</a> advocates using "_PACKAGE" to indicate that I'm creating package documentation, and says "This also works if there’s already a function called pkgname()."</p>

<p>I've also seen the <a href="http://r-pkgs.had.co.nz/man.html#man-packages" rel="noreferrer">R packages book</a> approach of using</p>

<pre><code>NULL
</code></pre>

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

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

<p>I expect to get documentation about my hello <strong>package</strong> with</p>

<pre><code>?hello
</code></pre>

<p>or perhaps something like</p>

<pre><code>package?hello
</code></pre>

<p>and I expect to get documentation about the included hello <strong>function</strong> with</p>

<pre><code>?hello()
</code></pre>

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

<p>I've already looked at questions about <a href="https://stackoverflow.com/questions/34439970/inline-package-overview-documentation-using-roxygen">package documentation</a> and <a href="https://stackoverflow.com/questions/13339021/devtools-roxygen-package-creation-and-rd-documentation/13348872#13348872">function documentation</a>, but things remain unclear to me.</p>

<p>Here's some details about my toy example:</p>

<p>hello/DESCRIPTION file:</p>

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

<p>hello/R/hello.R</p>

<pre><code>#' 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 &lt;- function() {
  print("Hello, world!")
}
</code></pre>

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

<p>Here's what the .Rd looks like:</p>

<pre><code>% 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()
}
</code></pre>