CODEWITHSUNDEEP
rfunctionpackagerstudiotidyverse
kiwi
kiwi

Reputation: 585

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

So I'm currently creating a package that generates a HTML report based on an active R script. This report can be created by running the function in the console. Looks something like this mypackage::myfunction()

Taking the tidyverse as an example, when you type in tidyverse:: some functions in this package appear in a popup dropdown list (you might have to press tab on your keyboard if it doesn't show immediately). When you hover over one of the functions a short summary/help text appears describing what it does. How can I add this to my package function?

tidyverse functions

Also, I noticed that for mypackage:: some functions appear which I prefer to not be shown to the end user. Is there a way I can remove some functions from this list?

Didn't find anything online so I would really appreciate any input on this :)

Upvotes: 4

Views: 981

Answers (1)

chrimaho
chrimaho

Reputation: 684

What you're seeing there are function docstrings. It is highly recommended that you write these for your functions also.

It would look like this (see 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))
}

And when you check it:

?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")

Further details about docstrings in R:

But just remember not to go overboard with your documentation. Here's some good resources for good code documentation:

Upvotes: 4

Related Questions