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()
}

Cutler

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!

Cutler

This doesn't seem to work for me now. I now get the \alias{package} that messes up linking. – Sigvard

I also have this problem coming back now. – Knobby

Answer 2

As pointed out by Johan Larsson and brendan in comments to this answer it seems like the alias for the function is overwritten by the package.

A solution is mentioned here and here. It is to add @aliases {pkgname}-package (in this case @aliases hello-package).

Annisannissa

Answer 3

I've seen it repeatedly said that you need to add @aliases {pkgname}-package, but it was not clear to me whether it was in the hello function comment block or in the package doc block.

Spoiler alert: it is in the package doc block:

#' 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.
#' @aliases hello-package
"_PACKAGE"

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

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

Galliett