[R-pkg-devel] questions about promptPackage(); <pkg>-package.Rd; help(package="<pkg>")

[Ben Bolker]

   I was advised to update the metadata in the "*-package.Rd" man page
of an old CRAN package (emdbook), which had gotten out of date.  As
suggested I used promptPackage() to build a new emdbook-package.Rd file.
I did that, but I was surprised/confused that it essentially dumped all
of the DESCRIPTION meta-data (using macros, not raw data) into the .Rd
file. The default information specified seems to replicate the results
of help(package="<pkg>"). If I hadn't double-checked I might
accidentally ending up pushing a <pkg>-package.Rd file that had a lot of
what I'd consider junk in it ...  Except for providing twice as many
places to find information [help(package="<pkg>") and
help("<pkg>-package")], which might help users who only knew about one
of these routes, I don't understand the benefit of these defaults.

  (Excerpts of *Writing R Extensions* section 2.1.4 "Documenting
packages" appended below, for reference.)

- Is it just that it's hard to prescribe/automatically write a "short
overview" statement for the package author?
- Is all this information intended as a reminder to the package author
of what's in the package, and they're expected to throw most of it out
when editing the file?  (When the information appears in the .Rd file as
e.g. \packageIndices{emdbook}, it's not actually that helpful as a
reminder ...)
- Or is the expectation that much of the DESCRIPTION metadata will also
be presented in <pkg>-package.Rd ?

    When I look at mature packages that have "<pkg>-package" pages (e.g.
mgcv, vegan, lattice) they seem to incorporate almost *none* of the
DESCRIPTION meta-information -- perhaps just \packageDescription{} and
\packageAuthor{}.

  Part of my confusion may stem from the package in question being very
small, so there's not very much one could say in <pkg>-package.Rd that's
not already said by the Title: and Description: fields in DESCRIPTION ...

  I ended up making a minimal emdbook-package.Rd file, but I wonder if
that's what's intended/what other developers would suggest here.

  cheers
    Ben Bolker

-----
> Packages may have an overview help page with an \alias
pkgname-package, e.g. ‘utils-package’ for the utils package, when
package?pkgname will open that help page.  ...

> ... Otherwise [if final=FALSE] (the default) comments will be inserted
giving suggestions for content.

> Apart from the mandatory \name and \title and the pkgname-package
alias, the only requirement for the package overview page is that it
include a \docType{package} statement. All other content is optional. We
suggest that it should be a short overview, to give a reader unfamiliar
with the package enough information to get started.