Adding more detailed documentation for get data set versions

R/get_dataset_versions.R

@@ -3,12 +3,34 @@
 #' @inheritParams api_url
 #' @param detail Level of detail to return. Given as a character string, it should be one of:
 #' "light" (default) or "full".
+#' Using "light" gives the following:
+#' \itemize{
+#'   \item version - version number
+#'   \item type - version type (major or minor)
+#'   \item total_rows - total number of rows in the listed version
+#'   \item date_released - release date of the version
+#'   \item version_title - name of the version release
+#'   \item time_period_start - first available time period in the data
+#'   \item time_period_start - latest available time period in the data
+#' }
+#'
+#' Using "full" adds the following in addition to the above:
+#' \itemize{
+#'   \item version_id - unique ID code for the data set version
+#'   \item status - publication status of the data set version
+#'   \item geographic_levels - geographic levels provided
+#'   \item filters - names of filters in the data set version
+#'   \item indicators - names of indicators in the data set version
+#'   \item notes - any additional information
+#'   }
+#'
+#' @return A data frame with X columns:
 #'
 #' @return Data frame listing all available versions of the given data set
 #' @export
 #'
 #' @examples
-#' get_dataset_versions(dataset_id = example_id(group="attendance"))
+#' get_dataset_versions(dataset_id = example_id(group = "attendance"))
 get_dataset_versions <- function(
     dataset_id,
     detail = "light",
@@ -21,7 +43,7 @@ get_dataset_versions <- function(
   validate_page_size(page_size)
 
   detail <- tolower(detail)
-  if(!(detail %in% c("light", "full"))){
+  if (!(detail %in% c("light", "full"))) {
     stop("The detail parameter should be either \"light\" or \"full\". Value passed: ", detail)
   }
 
@@ -62,25 +84,25 @@ get_dataset_versions <- function(
     }
   }
   response |> warning_max_pages()
-    results <- response$results |>
-      dplyr::select("version", "type", total_rows = "totalResults") |>
-      cbind(date_released = as.Date(response$results$published))|>
-      cbind(version_title = response$results$release$title)|>
-      cbind(time_period_start = response$results$timePeriod$start)|>
-      cbind(time_period_end = response$results$timePeriod$end)
-  if(detail == "full"){
-      results <- results |>
-        cbind(version_id = response$results$file$id)|>
-        cbind(
-          response$results |>
-            dplyr::select(
-              "status",
-              "notes",
-              geographic_levels = "geographicLevels",
-              "filters",
-              "indicators"
-              )
+  results <- response$results |>
+    dplyr::select("version", "type", total_rows = "totalResults") |>
+    cbind(date_released = as.Date(response$results$published)) |>
+    cbind(version_title = response$results$release$title) |>
+    cbind(time_period_start = response$results$timePeriod$start) |>
+    cbind(time_period_end = response$results$timePeriod$end)
+  if (detail == "full") {
+    results <- results |>
+      cbind(version_id = response$results$file$id) |>
+      cbind(
+        response$results |>
+          dplyr::select(
+            "status",
+            "notes",
+            geographic_levels = "geographicLevels",
+            "filters",
+            "indicators"
           )
-    }
+      )
+  }
   return(results)
 }

tests/testthat/test-get_dataset_versions.R

@@ -1,13 +1,14 @@
 test_that("get-data-versions returns results", {
   expect_gt(
-    get_dataset_versions(example_id(group="attendance")) |>
+    get_dataset_versions(example_id(group = "attendance")) |>
       nrow(),
-    0)
+    0
+  )
 })
 
 test_that("Check sensible error returns if no dataset_id given", {
   expect_error(
     get_dataset_versions(),
     "argument \"dataset_id\" is missing, with no default"
-    )
+  )
 })