CRAN 1.0.0

DESCRIPTION

@@ -1,16 +1,18 @@
 Type: Package
 Package: STATcubeR
-Title: R Interface for the STATcube REST API and Open Government Data
+Title: R Interface for the 'STATcube' REST API and Open Government Data
 Version: 1.0.0
-Date: 2024-11-28
+Date: 2024-11-29
 Authors@R: c(
     person("Bernhard", "Meindl", , "[email protected]", role = c("ctb", "cre")),
     person("Alexander", "Kowarik", , "[email protected]", role = c("ctb"),comment=c(ORCID="0000-0001-8598-4130")),
     person("Gregor", "de Cillia", , "", role = "aut"))
-Description: Import data from the STATcube REST API or from the open data
+Description: Import data from the 'STATcube' REST API or from the open data
     portal of Statistics Austria. This package includes a client for API
     requests as well as parsing utilities for data which originates from
-    STATcube.
+    'STATcube'. Documentation about 'STATcubeR' is provided by several vignettes 
+    included in the package as well as on the public 'pkgdown' page at 
+    <https://statistikat.github.io/STATcubeR/>.
 License: GPL (>= 2)
 URL: https://statistikat.github.io/STATcubeR/,
     https://github.com/statistikat/STATcubeR

R/browse.R

@@ -1,14 +1,16 @@
-#' Links to important STATcube and OGD pages
+#' Links to important 'STATcube' and 'OGD' pages
 #'
-#' A collection of links, to browse important STATcube pages.
+#' A collection of links, to browse important 'STATcube' pages.
 #'
 #' @inheritParams sc_key
 #' @name sc_browse
 NULL
 
-#' @describeIn sc_browse opens the home menu of STATcube
+#' @describeIn sc_browse opens the home menu of 'STATcube'
 #' @examples
 #' sc_browse()
+#' @return the URL of a specific webpage which is opened by default
+#' in a web browser.
 #' @export
 sc_browse <- function(server = "ext") {
   sc_url(sc_url_gui(server), "home")

R/cache.R

@@ -26,6 +26,12 @@
 #' @param verbose print instructions on how to set up caching persistently
 #'   via environment variables?
 #' @name sc_cache
+#' @return
+#' - for [sc_cache_enable()], [sc_cache_dir()]: the path to the cache-directory
+#' - for [sc_cache_disable()]: `TRUE`
+#' - for [sc_cache_enabled()]: `TRUE` if caching is enabled, `FALSE` otherwise
+#' - for [sc_cache_files()]: the content of the cache associated with a file
+#' - for [sc_cache_clear()]: `NULL`
 NULL
 
 #' @describeIn sc_cache enables caching for the current R session

R/od_cache.R

@@ -13,23 +13,24 @@
 #' ## inspect
 #' od_cache_summary()
 #' od_downloads()
-#' @details
-#' [od_cache_summary()] provides an overview of all contents of the cache through
-#' a data.frame. It has one row for each dataset and the following columns.
-#' All file sizes are given in bytes
-#' - **`id`** the dataset id
-#' - **`updated`** the last modified time for `${id}.json`
-#' - **`json`** the file size of `${id}.json`
-#' - **`data`** the file size of `${id}.csv`
-#' - **`header`** the file size of `${id}_HEADER.csv`
-#' - **`fields`** the total file size of all files belonging to fields (`{id}_C*.csv`).
-#' - **`n_fields`** the number of field files
+#' @return
+#' - [od_cache_summary()] provides an overview of all contents of the cache through
+#' a data.frame. It has one row for each dataset and returns a `data.frame` with#
+#' the following columns in which all file sizes are given in bytes.
+#'   - **`id`** the dataset id
+#'   - **`updated`** the last modified time for `${id}.json`
+#'   - **`json`** the file size of `${id}.json`
+#'   - **`data`** the file size of `${id}.csv`
+#'   - **`header`** the file size of `${id}_HEADER.csv`
+#'   - **`fields`** the total file size of all files belonging to fields (`{id}_C*.csv`).
+#'   - **`n_fields`** the number of field files
 #'
-#' [od_downloads()] shows a download history for the current cache
+#' - [od_downloads()] shows a download history for the current cache and returns
+#' a `data.frame` with the following columns:
 #'
-#' - **`time`** a timestamp for the download
-#' - **`file`** the filename
-#' - **`downloaded`** the download time in milliseconds
+#'   - **`time`** a timestamp for the download
+#'   - **`file`** the filename
+#'   - **`downloaded`** the download time in milliseconds
 #' @export
 od_cache_summary <- function(server = "ext") {
   cache_dir <- od_cache_path(server)

R/od_list.R

@@ -77,8 +77,9 @@ od_list <- function(unique = TRUE, server = c("ext", "red")) {
 #' and combines them into a `data.frame` so the datasets can easily be
 #' filtered based on categorizations, tags, number of classifications, etc.
 #'
+#' @details
 #' The naming, ordering and choice of the columns is likely to change.
-#' Currently, the following columns are provided.
+#' @return a `data.frame` with the following structure
 #'
 #' |**Column**|**Type**       | **Description**
 #' | ---------| -------       | -------------

R/od_table_save.R

@@ -19,6 +19,9 @@
 #'
 #' # cleanup
 #' file.remove(archive)
+#' @return
+#' - for [od_table_save()]: the path to the generated file
+#' - for [od_table_local()]: the OGD identifier
 #' @export
 od_table_save <- function(x, file = NULL) {
   stopifnot(inherits(x, "od_table"))

R/other_endpoints.R

@@ -11,6 +11,14 @@
 #' @name other_endpoints
 #' @inheritParams sc_key
 #' @inheritParams sc_schema
+#' @return
+#' - [sc_info()]: a `data.frame` with two columns identifying possible languages
+#' - [sc_rate_limit_table()], [sc_rate_limit_schema()], [sc_rate_limits()]: a `list` with elements
+#'   * `remaining`: how much requests can be sent until the rate limit is reached
+#'   * `limit`: the number of requests allowed per hour
+#'   * `reset`: a timestamp when the rate limit will be reset
+#' - [sc_rate_limits()]:
+
 NULL
 
 #' @describeIn other_endpoints
@@ -29,12 +37,10 @@ sc_info <- function(language = c("en", "de"), key = NULL, server = "ext") {
 }
 
 #' @describeIn other_endpoints
-#' returns a `3x1` dataframe with the following columns
-#' * `remaining` how much requests can be sent to the `/table`
-#'   endpoint until the rate limit is reached.
-#' * `limit` the number of requests allowed per hour.
-#' * `reset` a timestamp when the rate limit will be reset.
-#'   Usually, this should be less than one hour `after the current time.
+#' returns a `list` with information about current requests-limits with
+#' respect to the `/table` endpoint. It
+#' also shows when the limits reset which should be less than one hour
+#' after the current time.
 #' @export
 sc_rate_limit_table <- function(language = c("en", "de"), key = NULL, server = "ext") {
   response <- sc_check_response(httr::GET(
@@ -46,7 +52,11 @@ sc_rate_limit_table <- function(language = c("en", "de"), key = NULL, server = "
   rate_limit
 }
 
-#' @rdname other_endpoints
+#' @describeIn other_endpoints
+#' returns a `list` with information about current requests-limits with
+#' respect to the `/schema` endpoint. It
+#' also shows when the limits reset which should be less than one hour
+#' after the current time.
 #' @export
 sc_rate_limit_schema <- function(language = c("en", "de"), key = NULL, server = "ext") {
   response <- sc_check_response(httr::GET(

R/schema.R

@@ -23,6 +23,10 @@
 #'   `"field"` and `"valueset"`. For the catalogue, only `NULL` and `"folder"`
 #'   are applicable.
 #' @family functions for /schema
+#' @return
+#' - for [sc_schema()] and [sc_schema_db()]: an object of class `sc_schema`
+#' - for [sc_schema_flatten()]: a `data.frame`
+#' - for [sc_schema_catalogue()]: a `list`
 #' @export
 sc_schema <- function(id = NULL, depth = NULL,
                       language = NULL, key = NULL, server = "ext") {

R/table.R

@@ -19,7 +19,7 @@ base_url <- function(server = "ext") {
 
 #' @title  Class for /table responses
 #' @description R6 Class for all responses of the /table endpoint of the
-#'   STATcube REST API.
+#'   'STATcube' REST API.
 #' @keywords internal
 sc_table_class <- R6::R6Class(
   "sc_table",

R/table_custom.R

@@ -80,6 +80,10 @@
 #'   )
 #' )
 #' x$tabulate()
+#' @return
+#' - for [sc_table_custom()]: an object of class `sc_table`
+#' - for [sc_recode()]: a `list` that is a suitable input for parameter
+#' `"recode"` in [sc_table_custom()]
 #' @export
 sc_table_custom <- function(db, measures = c(), dimensions = c(),
                             language = c("en", "de"),

R/tabulate.R

@@ -3,7 +3,7 @@
 #' @description
 #' [sc_tabulate()] extracts the data in the table and turns it into a tidy
 #' data.frame. It applies labeling of the data and transforms time variables
-#' into a `Date` format if they satisfy certain STATcube Standards.
+#' into a `Date` format if they satisfy certain 'STATcube' standards.
 #'
 #' `sc_tabulate(table, ...)` is just an alias for `table$tabulate(...)` and
 #' was added so this rather complicated method can have a separate documentation
@@ -91,7 +91,7 @@
 #' ## table$tabulate(...) is an alias for sc_tabulate(table, ...)
 #' sc_tabulate(table, "C-A11-0")
 #'
-#' ######################### STATcube REST API #################################
+#' ######################## 'STATcube' REST API ################################
 #'
 #' @examplesIf sc_key_exists()
 #' table_tourism <- sc_table(sc_example("accomodation.json"), "de")
@@ -100,15 +100,7 @@
 #' table_tourism$tabulate("Saison/Tourismusmonat")
 #' table_tourism$tabulate("Saison/Tourismusmonat", "Ankünfte")
 #' table_tourism$tabulate("Ankünfte")
-#'
-#' ## TODO: param annotations does not work currently
-#' if (FALSE) {
-#'   table_trade <- sc_table(sc_example("foreign_trade.json"), "de")
-#'   tt <- sc_tabulate(table_trade, "Berichtsjahr", "Import, Wert in Euro",
-#'                     annotations = TRUE)
-#'   tt
-#'   str(tt[['Import, Wert in Euro_a']])
-#' }
+#' @return a `data.frame`
 #' @export
 sc_tabulate <- function(table, ..., .list = NULL, raw = FALSE,
                         parse_time = TRUE, recode_zeros = inherits(table, "sc_table"),