如何将弹出式帮助文本添加到 RStudio 中用户创建的包中的函数？

Question

所以我目前正在创建一个包，它根据活动的 R 脚本生成 HTML 报告。此报告可以通过运行控制台中的功能创建。看起来像这样 mypackage::myfunction()

以tidyverse为例，当你输入tidyverse::时，这个包中的一些函数会出现在弹出的下拉列表中（如果没有，你可能需要按键盘上的Tab键' t立即显示）。当您将鼠标悬停在其中一个功能上时，会出现一个简短的 summary/help 文本来描述它的作用。如何将其添加到我的包功能中？

此外，我注意到 mypackage:: 出现了一些我不希望向最终用户显示的功能。有什么办法可以从这个列表中删除一些函数吗？

没有在网上找到任何东西，所以我非常感谢对此的任何意见:)

Answer 1

您看到的是函数文档字符串。强烈建议您也为您的函数编写这些。

看起来像这样（参见 source）：

library(docstring)

mypaste <- function(x, y = "!"){
  #' Paste two items
  #' 
  #' @description This function pastes two items
  #' together.  
  #'
  #' By using the description tag you'll notice that I
  #' can have multiple paragraphs in the description section
  #' 
  #' @param x character. The first item to paste
  #' @param y character. The second item to paste Defaults to "!" but
  #' "?" would be pretty great too
  #' @usage mypaste(x, y)
  #' @return The inputs pasted together as a character string.
  #' @details The inputs can be anything that can be input into
  #' the paste function.
  #' @note And here is a note. Isn't it nice?
  #' @section I Must Warn You:
  #' The reference provided is a good read.
  #' \subsection{Other warning}{
  #'   It is completely irrelevant to this function though.
  #' }
  #' 
  #' @references Tufte, E. R. (2001). The visual display of 
  #' quantitative information. Cheshire, Conn: Graphics Press.
  #' @examples
  #' mypaste(1, 3)
  #' mypaste("hey", "you")
  #' mypaste("single param")
  #' @export
  #' @importFrom base paste

  return(paste(x, y))
}

当你检查它时：

?mypaste

Paste two items

Description:
     This function pastes two items together.
     By using the description tag you'll notice that I can have
     multiple paragraphs in the description section

Usage:
     mypaste(x, y)
     
Arguments:
       x: character. The first item to paste
       y: character. The second item to paste Defaults to "!" but "?" would be pretty great too

Details:
     The inputs can be anything that can be input into the paste
     function.

Value:
     The inputs pasted together as a character string.

I Must Warn You:
     The reference provided is a good read.

Other warning:
       It is completely irrelevant to this function though.


Note:
     And here is a note. Isn't it nice?

References:
     Tufte, E. R. (2001). The visual display of quantitative
     information. Cheshire, Conn: Graphics Press.

Examples:
     mypaste(1, 3)
     mypaste("hey", "you")
     mypaste("single param")

R 中有关文档字符串的更多详细信息：

The tidyverse Style Guide: Documentation
Introduction to docstrings
Is there a sensible way to do something like docstrings in R?
docstring

但请记住不要过度使用您的文档。这里有一些好的代码文档的好资源：

如何将弹出式帮助文本添加到 RStudio 中用户创建的包中的函数？

How to add popup help text to functions in a user-created package in RStudio?

r

function

package

rstudio

tidyverse