Standardize documentation in package.R

[nanxstats]

We received two communications regarding the roxygen2 documentation issues in R/package.R:

Issue 1

You have file 'gsDesign/man/gsDesign-package-overview.Rd' with \docType{package}, likely intended as a package overview help file, but without the appropriate PKGNAME-package \alias as per "Documenting packages" in R-exts.

This seems to be the consequence of the breaking change

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

in roxygen2 7.0.0 (2019-11-12) having gone unnoticed, see https://github.com/r-lib/roxygen2/issues/1491.

As explained in the issue, to get the desired PKGNAME-package \alias back, you should either change to the new approach and document the new special sentinel

"_PACKAGE"

or manually add

@aliases gsDesign-package

if remaining with the old approach.

Issue 2

You have file gsDesign/man/gsDesign-package-overview.Rd as a package overview help file which in \details gives a table with the basic package DESCRIPTION metadata.

At least the given version disagrees with the actual package version (meta: 3.5.0, docs: 2).

Perhaps simply remove the whole table: the package DESCRIPTION metadata are provided at the start of CRAN's PDF refmans, and can conveniently be accessed from the dynamic help system.

I also feel that the two blocks of documentation in R/package.R is a bit unconventional - because they are not functions and are overview of a group of functions. They also don't look logic in the reference manual PDF. I suggest that we standardize them by:

1. Use usethis::use_package_doc() to generate standard package doc page.
2. Move the content of the two blocks in R/package.R to (new?) vignette(s).
3. Link the vignette(s) in the pkgdown function reference page section description like in extending ggplot2.