r - 加载 `library(packagename)` 时提醒用户包小插曲的最佳实践？

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.

5年前关闭。




Improve this question




我正在编写一个 R 包，并在文档小插曲上花费了大量时间。我想知道我是否应该添加类似的东西

.onAttach <- function( libname , pkgname ){
   packageStartupMessage("use `browseVignettes('packagename')` to see vignettes")
}

当用户打电话时会立即显示

library(packagename)

告知用户包装小插图的最佳方式是什么？或者只是假设用户会在没有明确通知的情况下寻找它们？

Answer 1

无处不在的小插曲

在日常 R 用户眼中，关于小插图的注意事项很少......

可在 CRAN 包页面上找到(如果作者有包，这是一个很好的包质量检查!)

添加到包二进制文件并通过 browseVignettes(package = "pkgname") 显示在小插图帮助部分[正如你所指出的]

内嵌R包源码

可以在 /demos 中使用小插图中的嵌入代码作为单独的脚本演示通过 demo()

最重要的部分:没有一个用户真正了解小插曲。

因此，如果您在软件包文档上花费大量时间，您可能至少应该在启动时指出存在这样的功能。

漏洞利用 packageStartupMessage()内 .onAttach()为了用户的利益。

包加载时，控制台比较清晰，用户会 绝对看到红色文本，因为普通蓝色 R 文本之间的对比度相对较高(假设没有 crayon)。但是，在某些情况下，提醒用户存在小插曲是没有意义的。

如果 session 是非交互式的(例如 bash 脚本)。

如果用户是 R 'pro'

如果用户长时间使用您的包，导致用户无视消息。

因此，实现不佳 packageStartupMessage() 是不利的。 .

因此，我建议在四种不同条件下引入启动消息。

(全部)通过查询 interactive() 来检查是否有人在场.如果是，则继续:

(标准) 至少有3条不同的启动消息列表，每次启动随机选择一个显示；

(正常)随机生成一个数字来决定是否应该显示启动信息；

(Pro) 在 x 之后计算包的加载量包加载会终止启动消息，直到用户重新安装包。

为简单起见，我接下来将提出两个解决方案，它们遵循 (1) - (3) 以及 (1) 和 (4) 的原则。

随机选择包提示

在这个版本中，我们试图简单地检查人，提供添加包加载消息的中断，并随机选择一个提示来显示。在 base 的范围之外只需要一个依赖项, stats::runif命令生成 [0,1] 之间的概率。

#' @importFrom stats runif
.onAttach <- function(...) {

  # If interactive, hide message
  # o.w. check against rng seed.
  if (!interactive() || stats::runif(1) > 0.5){
     return()
  }

  # Create a list of helpful tips
  pkg_hints = c(
    "Check for updates and report bugs at https://cran.r-project.org/web/packages/pkgname/.",
    "Use `suppressPackageStartupMessages()` to remove package startup messages.",
    "To see the user guides use `browseVignettes('pkgname')`"
  )

  # Randomly pick one hint
  startup_hint = sample(pkg_hints, 1)

  # Display hint
  packageStartupMessage(paste(strwrap(startup_hint), collapse = "\n"))
}

计算包裹装载量

为了使用计数器，我们利用保存到包的安装目录而不是“工作”目录/用户空间的能力。这有一些与之相关的问题，我将简要提及:

用户可能只有查看权限但不能修改 system库(用户库没问题)。

因此，他们将 总是 在此方法下接收包提示，因为它们不能增加计数器。

如果包裹在 system 中，计数器可能会被共享图书馆。

这将导致快速使用所有提示。

错误日志的大小可能会增加。

当然，您可以通过 R_USER or HOME environment variables 在用户空间中创建自己的文件夹。来否定这些问题。 (练习留给读者，提示:使用 Sys.getenv() 和 dir.create() 。)

无论如何，此功能的优点之一是稍后您可能会在包中包含“发送包使用情况统计信息”功能。这实际上会给出一个相当准确的 - 电话主页 - 统计数据与当前的 RStudio CRAN 镜像包下载信息。但是，我离题了。

为了使这种方法起作用，我们需要对提供给 CRAN 的初始包做更多的准备工作。具体来说，我们可能应该通过以下方式预先设置一个计数器:

# Set working directory to package
setwd("package_dir")

# Create the inst directory if it does not exist
if(!dir.exists("inst")){
  dir.create("inst")
}

# Create a counter variable
pkg_count = 0

# Save it into a .rda file
save(pkg_count, file="inst/counter.rda")

现在，进入 .onAttach()反执行!

.onAttach <- function(...){
  if (!interactive()) return()

  # Get the install directory location of the counter
  path_count = system.file("counter.rda", package = "pkgname")

  # Suppress messages by default
  displayMsg = FALSE

  # Are we able to load the counter?
  a = tryCatch(load(path_count), error = function(e){"error"}, warning = function(e){"warning"})

  # Set error variable
  count_error = a %in% c("error","warning")

  # Check if the count is loaded
  if(!count_error){

    # Check if load count is low... 
    if(pkg_count < 10){
      pkg_count = pkg_count + 1

      # Try to save out
      try(save(pkg_count, file = path_count), silent=TRUE)
      displayMsg = T
    }
  }

  # Display message (can be suppressed with suppressPackageStartupMessages)
  if(displayMsg){
    packageStartupMessage("use `browseVignettes('packagename')` to see vignettes")
  }
}

最后一个想法

请记住，如果您有任何软件包依赖项(例如 Depend: 中的 DESCRIPTION)，它们可能有自己的一组启动消息，将显示 之前 那些写在你的包里的。