Lesson Contribution for #8 Making Packages R

[Talishask]

I'm a member of The Carpentries Core Team and I'm submitting this issue on behalf of another member of the community. In most cases, I won't be able to follow up or provide more details other than what I'm providing below.

---

There seems to be an inconsistency in the lesson concerning how to include functions in the package.

Under the section headed '.R files' we read:

'Functions don't all have to be in one file or each in separate files. How you organize them is up to you. Suggestion: organize in a logical manner so that you know which file holds which functions.'

In the section immediately below, 'Making your first R package', however, we read:

'Add our functions to the R directory. Place each function into a separate R script and add documentation like this:

#' Converts Fahrenheit to Celsius
#'
#' This function converts input temperatures in Fahrenheit to Celsius.
#' @param temp_F The temperature in Fahrenheit.
#' @return The temperature in Celsius.
#' @export
#' @examples
#' fahrenheit_to_kelvin(32)

fahrenheit_to_celsius <- function(temp_F) {
  temp_C <- (temp_F - 32) * 5 / 9
  return(temp_C)
}'

I don't believe the discrepancy is serious and it should work whether functions are each in a separate .R file or instead several functions are grouped together in different .R files according to use. However, for a novice learner, the apparent contradiction in the instructions might be somewhat disconcerting.

In general, the description of the package creation process is a bit too semaphoric. In particular, how one needs to move amongst directories in the process of creating the package, populating the R subdirectory with R scripts, and automating the creation of documentation using the function 'document()', could be made substantially clearer.

Finally, there seems to be some issue with the compatibility of the description of the package creation process as given and R versions 4.0 and greater. I am working to clarify the matter by pursuing the matter on Stack Overflow.