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.

[hadley]

Change was made in 29db38f as part of some other refactoring with comment " @docType package no longer adds -package alias as this broke encapsulation and was only mildly useful."

[hadley]

I'd appreciate someone would take a look at #1535 and confirm that the approach makes sense — the basic is to make @docType package essentially an alias for _PACKAGE (with deprecation message), ensuring that the behaviour of the two can no longer drift out of sync.