broken @docType package documentation

[bastistician]

roxygen2 7.0.0 (2019-11-12) had the breaking change

• Using @docType package no longer automatically adds a -package alias.
  Instead document _PACKAGE to get all the defaults for package documentation

from 29db38f.

However, thousands of packages still use the old way (that was still recommended a year ago)

#' @docType package
#' @name pkgname
NULL

not being aware that they should

• either document the new "special sentinel" _PACKAGE
• or manually add @aliases <pkgname>-package

because they no longer automatically get that alias that is required for a package overview page to be found via package?pkgname. As a consequence, CRAN now has thousands of packages where this help request no longer works.

Could roxygen2 warn users when there is a @docType package block without corresponding @aliases (and possibly recommend the new _PACKAGE feature)?

[bastistician]

Addendum: I noticed that some packages do use the "_PACKAGE" syntax introduced long ago via @krlmlr's #392, but explicitly remove the default aliases via @aliases NULL (e.g., krlmlr/enc@3ee7849) producing a help page without alias, unaccessible from dynamic help().

I think it would be very useful if roxygen2 actively warned its users about the breaking change from 7.0.0, i.e., when the old approach @docType package on NULL is used (without manually specifying @aliases pkgname-package) and recommend documenting "_PACKAGE". Maybe @krlmlr would have an idea?

[MichaelChirico]

Just came to post the same -- the current warning is misleading, routing users to the more awkward #' @name pkgname-package approach:

[pkgname-package.R:10] Block must have a @name
ℹ Either document an existing object or manually specify with @name

The "_PACKAGE" sentinel approach strikes me as a bit redundant (we've already written #' @docType package), but if this is the requirement we should be steering users there more helpfully.

[zachmayer]

This is a really, really dumb question, but how do I make a _PACKAGE document? Is this just like a new file I add to package folder? Is a _PACKAGE something else?

[MichaelChirico]

@zachmayer maybe a useful reference example

https://github.com/tidyverse/tibble/blob/main/R/tibble-package.R

[zachmayer]

lol I was overthinking it. As always a reference was all I needed. Thank you!

https://github.com/tidyverse/tibble/blob/main/R/tibble-package.R#L62

[bbolker]

tl;dr can anyone explain why I'm getting a spurious \alias{-package} in my .Rd file?

Confused on this issue, don't know if anyone can help me out. I'm maintaining a legacy package. The roxygen stuff at the head of the package-defining .R file looks like this:

#' @rdname margins
#' @name margins
#' @aliases margins-package
#' @docType package
#' @title Marginal Effects Estimation

But the head of margins.R looks like this:

\docType{package}
\name{margins}
\alias{-package}
\alias{margins}
\alias{margins-package}

This is with roxygen2 7.3.2. I could rearrange everything to follow the now-recommended _PACKAGES approach, but if I can minimally fix what I'm doing wrong I would prefer it. (Of course I could also manually edit the .Rd file to get rid of the spurious alias, which is what I'll do for now ...)

Here's the repo if anyone wants to look at the original.