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
______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
