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

[Duncan Murdoch]

On 02/12/2020 12:57 p.m., Konrad Rudolph wrote:
> 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.

I haven't tried this, but I believe if you define functions with the 
right name and header in your package but don't export them the warning 
will go away.

If that doesn't work (or defining those causes other issues), a more 
involved workaround would be to change the \docType{} declaration for 
the help page.  \docType{package} is the most free-form, but you might 
get warned if you have two of them.  \docType{data} might be flexible 
enough.  If you do this, you won't use \usage{} or \arguments{}, you'll 
put together your own sections using \section{Usage}{ ... } and 
\section{Arguments}{ ... } and try to get the formatting right.

Duncan Murdoch

> 
> [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
>