data-raw/helper_functions/check_returns_in_documentation.R

In EvolEcolGroup/pastclim: Manipulate Time Series of Palaeoclimate Reconstructions

# with wd set to the root of the package, source this script
# it will return a list of the map pages missing returns
# note that map pages for datasets don't need returns.

## running: grep -Ril -F "\value" ./man/

check_returns_in_documentation <- function() {
  # get a list of all files in the man directory
  all_files <- dir("./man")

  ## there are a number of files that we don't expect to have @returns:

  ## documentation of external dataset; these don't have a usage tag
  # functions and internal data have usage
  files_with_usage <- basename(system2(
    command = "grep",
    args = c("-Ril -F ", shQuote("\\usage"), " ./man/"),
    stdout = TRUE
  ))
  # but documentation of external datasets do not
  external_data <- all_files[!all_files %in% files_with_usage]
  # the above also catches any subdirectories that are accidentally listed

  ## internal data are of Type data
  internal_data <- basename(system2(
    command = "grep",
    args = c("-Ril -F ", shQuote("\\docType{data}"), " ./man/"),
    stdout = TRUE
  ))
  ## the package documentation
  package_docs <- basename(system2(
    command = "grep",
    args = c("-Ril -F ", shQuote("\\docType{package}"), " ./man/"),
    stdout = TRUE
  ))
  excluded_files <- c(internal_data, external_data, package_docs)
  ## now remove those files from our list
  all_files <- all_files[!all_files %in% excluded_files]

  # get a list of documentation Rd files with \value, as generated by @returns
  # note the additional \ to run through system 2
  files_with_value <- basename(system2(
    command = "grep",
    args = c("-Ril -F ", shQuote("\\value"), " ./man/"),
    stdout = TRUE
  ))
  # and finally check if there is any stray file left
  files_missing_returns <- all_files[!all_files %in% files_with_value]

  if (length(files_missing_returns) != 0) {
    stop(paste(
      "There are some files that miss @return:\n",
      paste(files_missing_returns, collapse = ", ")
    ))
  } else {
    return("Success")
  }
}
check_returns_in_documentation()