4

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 :)

kiwi
  • 565
  • 3
  • 11
  • 1
    The pop up just takes the description from the the help page. If you fill those out in your package, they should show up. To avoid some functions from being in the namespace when your package is loaded, remove `#' @export` from your function's buildup page. – Phil Mar 01 '21 at 15:07

1 Answers1

4

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:

chrimaho
  • 580
  • 4
  • 22