[R-pkg-devel] How to avoid R CMD check warning for documentation of non-package functions?

[Konrad Rudolph]

My package provides infrastructure support for callback functions
defined in special environments in user code. They are conceptually
similar (in fact, almost identical) to the `.onLoad` etc. “hooks for
namespace events” in base R [1]. Now I’m adding documentation for
these functions, via the following Rd code (or the equivalent roxygen2
code annotating a `NULL` value):

```
\name{topicname}
\alias{topicname}
\alias{onload}
\title{Hooks for environment events}
\usage{
onload(env)
}
\arguments{
\item{env}{the environment}
}
\description{
Short description
}
```

Unfortunately, this causes an `R CMD check` warning:

>  Functions or methods with usage in documentation object 'topicname' but not in code:
>     ‘onload’

Right: this function does not exist in my package, and it *should not*
exist in the package. Yet I do need to document it for users. What is
the recommended way for doing so? In fact, from my reading of the R
source, the base R documentation of ‘ns-hooks’ doesn’t seem to do
anything special, and would presumably also cause this warning.

I’m open to doing this differently, but I’d strongly prefer if these
functions had their own help topic, with their own “usage” section. I
don’t just want to add them as a custom section to the package
documentation topic if this is at all avoidable.

[1]: https://stat.ethz.ch/R-manual/R-devel/library/base/html/ns-hooks.html

PS: A note on API design, I considered doing this differently: rather
than define hooks via “special names”, users would define them by
passing callbacks to a call to a package function; e.g.
`mypkg::define_onload(function (env) { … })`. This would be
conceptually similar to R’s `setHook` [2]. However, from the user’s
point of view there’s no advantage to doing it this way, and it’s more
verbose. Defining callbacks via special names has ample precedence,
both in R and in other languages. And I don’t think `R CMD check`
warnings should dictate API design in this manner.

[2] https://stat.ethz.ch/R-manual/R-devel/library/base/html/userhooks.html

-- 
Konrad Rudolph // @klmr