R packages: Documenting

[maurolepore]

• ds-incubator chapter.
• Video recording.
• Slides.

Resources:

• R packages > Whole game
• pkgdown::build_articles()
• pkgdown::build_home()
• usethis functions for package development and setup

[maurolepore]

"nice-to-have" for contributors

It would be "nice to have" contributions documented in full from the beginning, but if that is not the case, the developer would work with the contributor to complete and clarify the documents.

"must-have" for developers

@cjyetman recommended to always document explicitly the expected type of each argument to a function. @2diiKlaus endorsed the comment and asks to do it in all packages we build.

I would like to develop a template for documenting arguments. Eventually this could be shared as an addin that works similarly to "Insert Roxygen Skeleton". But for now I would like to brainstorm ideas for what the template should look like.

Examples:

glue::glue() is one example. The output looks nice but the source code seems complicated.

A simpler template might be:

#' @param First sentence describing the type of expected data, or 
#'   its class (e.g. "data.frame"), or other details about the required
#'   structure of the data. Optional second sentence about other 
#'   general details]. 

Example:

#' @param loanbook A "data.frame" with columns `a`, and `b`. A 
#'   dataset like [r2dii.dataraw::loanbook_demo].

@cjyetman, @jdhoffa, do you have any suggestion?

[jdhoffa]

This looks great to me.

[cjyetman]

I’ll look for some good examples and share