merge dplyr and galah versions of same functions in help files

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: galah
 Type: Package
-Title: Biodiversity Data from the Living Atlas Community
+Title: Download Biodiversity Data from the GBIF Node Network
 Version: 1.5.3
 Authors@R:
     c(person(given = "Martin",
@@ -18,9 +18,13 @@ Authors@R:
              family = "Newman",
              email = "[email protected]",
              role = "aut"))
-Description: The living atlas community provides tools to enable users to find, 
-    access, combine and visualise data on biodiversity. 'galah' enables the R 
-    community to directly access data and resources hosted by the living atlases.
+Description: The Global Biodiversity Information Facility 
+    (GBIF, <https://www.gbif.org>) sources data from an international network of 
+    data providers, known as 'nodes'. Several of these nodes - the 'living 
+    atlases' (<https://living-atlases.gbif.org>) - maintain their own
+    web services using a codebase originally developed by the Atlas of Living 
+    Australia (ALA, <https://www.ala.org.au>). 'galah' enables the R community 
+    to directly access data and resources hosted by GBIF and its partner nodes.
 Depends:
     R (>= 4.1.0)
 Imports:

R/atlas_counts.R

@@ -36,6 +36,7 @@
 #' be replaced by the current query
 #' @importFrom glue glue_collapse
 #' @importFrom dplyr bind_rows
+#' @rdname atlas_counts
 #' @return
 #' 
 #' An object of class `tbl_df` and `data.frame` (aka a tibble) returning: 

R/count.R

@@ -1,16 +1,9 @@
-#' Count for object of class `data_request`
-#' @description `r lifecycle::badge("experimental")` 
+#' @rdname atlas_counts
 #' @param x An object of class `data_request`, created using [galah_call()]
 #' @param wt currently ignored
 #' @param ... currently ignored
 #' @param sort currently ignored
 #' @param name currently ignored
-#' @param type `string`: one of `c("record", "species")`. Defaults to
-#' "record". If "species", the number of species matching the criteria will be
-#' returned, if "record", the number of records matching the criteria will be
-#' returned.
-#' @seealso  [atlas_counts()], with which this function is synonymous.
-#' @importFrom dplyr count
 #' @export
 count.data_request <- function(x, ..., wt, sort, name, type = c("record", "species")){
   type <- match.arg(type)

R/deprecated_functions.R

@@ -7,6 +7,10 @@
 #' 
 #' @keywords internal
 #' @export
+#' @param query A vector of taxonomic names (for `select_taxa()`) or a valid
+#' well-known text string (for `select_locations()`).
+#' @param is_id Logical: Does the information provided in `query` consist of 
+#' taxonomic identifiers (TRUE), or taxonomic names (FALSE, the default).
 #' @name deprecated
 #' @return All deprecated functions return a `tibble`.
 select_taxa <- function(query, is_id = FALSE) {
@@ -22,7 +26,10 @@ select_taxa <- function(query, is_id = FALSE) {
 
 #' @description
 #' Use [galah_select()] instead of `select_columns()`.
-#' 
+#' @param ... Queries consisting of field names (for `select_columns()`) or 
+#' equations (for `select_filters()`).
+#' @param group optional; the name of a group of columns to include. See 
+#' `galah_select()` for details.
 #' @keywords internal
 #' @export
 #' @name deprecated
@@ -34,7 +41,7 @@ select_columns <- function(..., group){
 
 #' @description
 #' Use [galah_filter()] instead of `select_filters()`.
-#'
+#' @param profile String: The name of a valid ALA profile.
 #' @keywords internal
 #' @export
 #' @name deprecated
@@ -60,7 +67,15 @@ select_locations <- function(query) {
 
 #' @description 
 #' Use [atlas_occurrences()] instead of `ala_occurrences()`.
-#'
+#' @param taxa A tibble created with `galah_identify()`
+#' @param filters A tibble created with `galah_filter()`
+#' @param locations A tibble created with `galah_geolocate()`
+#' @param columns A tibble created with `galah_select()`
+#' @param mint_doi Logical: Should a DOI be created for this download? Defaults
+#' to FALSE.
+#' @param doi String: Optional ALA DOI to download
+#' @param refresh_cache Logical: Should the data be re-downloaded to the cache?
+#' Defaults to FALSE.
 #' @keywords internal
 #' @export
 #' @name deprecated
@@ -86,7 +101,9 @@ ala_occurrences <- function(taxa = NULL, filters = NULL, locations = NULL,
 
 #' @description
 #' Use [atlas_counts()] instead of `ala_counts()`.
-#'
+#' @param limit Integer: How many records should be downloaded? Defaults to 100.
+#' @param type String: Should counts be made of the number of `"records"` 
+#' (default) or `"species"`?
 #' @keywords internal
 #' @export
 #' @name deprecated
@@ -131,7 +148,7 @@ ala_species <- function(taxa = NULL, filters = NULL, locations = NULL,
 
 #' @description
 #' Use [atlas_taxonomy()] instead of `ala_taxonomy()`.
-#' 
+#' @param down_to A tibble created with `galah_down_to()`
 #' @keywords internal
 #' @export
 #' @name deprecated
@@ -146,7 +163,7 @@ ala_taxonomy <- function(taxa, down_to){
 
 #' @description
 #' Use [atlas_media()] instead of `ala_media()`.
-#' 
+#' @param download_dir Path to a directory in which to place media files
 #' @keywords internal
 #' @export
 #' @name deprecated
@@ -170,7 +187,7 @@ ala_media <- function(taxa = NULL,
 
 #' @description 
 #' Use [atlas_citation()] instead of `ala_citation()`.
-#' 
+#' @param data A tibble returned by `ala_occurrences()`
 #' @keywords internal
 #' @export
 #' @name deprecated
@@ -245,7 +262,7 @@ find_atlases <- function() {
 
 #' @description 
 #' Use [galah_config()] instead of `ala_config()`.
-#'
+#' @param profile_path Optional path to profile information
 #' @keywords internal 
 #' @export
 #' @name deprecated
@@ -258,7 +275,7 @@ ala_config <- function(..., profile_path = NULL) {
 
 #' @description 
 #' Use [show_values()] instead of `search_field_values()`
-#'
+#' @param field String: A valid field for which to display entries.
 #' @keywords internal 
 #' @export
 #' @name deprecated
@@ -272,7 +289,7 @@ search_field_values <- function(field){
 
 #' @description 
 #' Use [show_values()] instead of `search_profile_attributes()`
-#'
+#' 
 #' @keywords internal 
 #' @export
 #' @name deprecated

R/filter.R

@@ -1,15 +1,5 @@
-#' Narrow a query by specifying filters
-#'
-#' "Filters" are arguments of the form `field` `logical` `value` that are used
-#' to narrow down the number of records returned by a specific query.
-#' For example, it is common for users to request records from a particular year
-#' (`year == 2020`), or to return all records except for fossils
-#'  (`basisOfRecord != "FossilSpecimen"`).
-#'  
-#' `r lifecycle::badge("experimental")` 
-#' @seealso  [galah_filter()], with which this function is synonymous.
+#' @rdname galah_filter
 #' @param .data An object of class `data_request`, created using [galah_call()]
-#' @param ... filters, in the form `field logical value`
 #' @export
 filter.data_request <- function(.data, ...){
   dots <- enquos(..., .ignore_empty = "all")

R/galah_filter.R

@@ -13,7 +13,7 @@
 #' `galah_filter` uses non-standard evaluation (NSE),
 #' and is designed to be as compatible as possible with `dplyr::filter()`
 #' syntax.
-#'
+#' @rdname galah_filter
 #' @param ... filters, in the form `field logical value`
 #' @param profile 
 #'    `r lifecycle::badge("soft-deprecated")` Use `galah_apply_profile` instead. 

R/galah_polygon.R

@@ -6,7 +6,10 @@
 #' (i.e. have too many characters or too many vertices) or they will not be
 #' accepted in a query to the ALA.
 #'
-#' @param ... a single `sf` object, WKT string or shapefile. 
+#' @rdname galah_polygon
+#' @param ... When supplied to `galah_polygon()`, a single `sf` object, WKT 
+#' string or shapefile. Currently ignored when supplied to 
+#' `st_crop.data_request()`
 #' @details WKT strings longer than 10000 characters and 
 #' `sf` objects with more than 500 vertices will not be
 #' accepted by the ALA. Some polygons  may need to be simplified.

R/slice_head.R

@@ -1,13 +1,14 @@
 #' Slice for object of class `data_request`
 #' 
-#' @description `r lifecycle::badge("experimental")` 
 #' This is a simple function to set the 'limit' argument in [atlas_counts()]
 #' using `dplyr` syntax.
 #' @param .data An object of class `data_request`, created using [galah_call()]
 #' @param ... currently ignored
 #' @param n The number of rows to be returned. If data are grouped 
 #' (using [group_by]), this operation will be performed on each group.
 #' @param prop currently ignored
+#' @returns An updated object of class `data_request`, whose `limit` argument
+#' is set with an integer value provided by `n`.
 #' @export
 slice_head.data_request <- function(.data, ..., n, prop){
   update_galah_call(.data, limit = n)

R/st_crop.R

@@ -1,19 +1,6 @@
-#' Narrow a query to within a specified polygon
-#'
-#' Restrict results to those from a specified area. Areas must be polygons. 
-#' Polygons must be supplied as an `sf` object, a 'well-known text' (WKT) 
-#' string, or a shapefile. Polygons and shapefiles must not be overly complex
-#' (i.e. have too many characters or too many vertices) or they will not be
-#' accepted in a query to the ALA.
-#'  
-#' `st_crop` is masked from `sf`, but when piped after [galah_call()], is 
-#' functionally  synonymous with [galah_polygon()]
-#' 
-#' `r lifecycle::badge("experimental")` 
-#' @seealso  [galah_polygon()], with which this function is synonymous.
+#' @rdname galah_polygon
 #' @param x An object of class `data_request`, created using [galah_call()]
 #' @param y A single `sf` object, WKT string or shapefile
-#' @param ... currently ignored
 #' @export
 st_crop.data_request <- function(x, y, ...){
   update_galah_call(x, geolocate = parse_polygon(y))