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

Question

I am studying the use of roxygen. I see that rd vignette protects the use of "_PACKAGE" to indicate that I am creating package documentation, and says: "This also works if theres already a function called pkgname ().

I also saw R packages book use

NULL 

with the specified @docType and @name, but when I try to make an example of toys with any approach, it does not work as I expect.

As an example of toys, I would like to make a hello package that includes the hello () function.

I expect to receive documentation about my welcome package with

 ?hello 

or maybe something like

 package?hello 

and I expect to receive documentation about the included welcome feature from

 ?hello() 

Where am I wrong? - implementation with roxygen, the way I'm trying to request documentation, wrong expectations or something else?

I have already addressed questions about documentation for package documentation and function documentation , but everything remains unclear to me.

Here are 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 = " [e-mail] ", role = c("aut", "cre")) Description: More about what it does (maybe more than one line) License: MIT LazyData: TRUE RoxygenNote: 5.0.1.9000 

hi / P / 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!") } 

In this case, after running document() , hello / man / hello.Rd is generated. It contains a combination of the descriptions that I wrote for the hello package and the hello () function. ?hello and ?hello() both return this .Rd file.

Here is what .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. This overrides the default naming” and “sometimes you need to restart R because something doesn't work 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 the hello-package.Rd and hello.Rd files. After loading library(hello) , package?hello provides documentation on packages, and ?hello provides functional documentation, as I shot!

Thanks again @hadley!