Merge pull request #415 from ropensci/docs

Use markdown style internal links in roxygen docs + improvements in docs

Author: jmaspons

R/elevation.R

@@ -3,9 +3,9 @@
 #' Add elevation data to a previously-extracted OSM data set, using a
 #' pre-downloaded global elevation file from
 #' \url{https://srtm.csi.cgiar.org/srtmdata/}. Currently only works for
-#' `SC`-class objects returned from \link{osmdata_sc}.
+#' `SC`-class objects returned from [osmdata_sc()].
 #'
-#' @param dat An `SC` object produced by \link{osmdata_sc}.
+#' @param dat An `SC` object produced by [osmdata_sc()].
 #' @param elev_file A vector of one or more character strings specifying paths
 #' to `.tif` files (or anything that \pkg{terra} can read) containing global
 #' elevation data. `.zip` files will be uncompressed.

R/get-osmdata-df.R

@@ -1,11 +1,11 @@
-#' Return an OSM Overpass query as a \link{data.frame} object.
+#' Return an OSM Overpass query as a [data.frame] object.
 #'
 #'
 #' @inheritParams osmdata_sf
 #' @param q An object of class `overpass_query` constructed with
-#'      \link{opq} and \link{add_osm_feature} or a string with a valid query, such
+#'      [opq()] and [add_osm_feature()] or a string with a valid query, such
 #'      as `"(node(39.4712701,-0.3841326,39.4713799,-0.3839475);); out;"`.
-#'      May be be omitted, in which case the attributes of the \link{data.frame}
+#'      May be be omitted, in which case the attributes of the [data.frame]
 #'      will not include the query. See examples below.
 #' @param stringsAsFactors Should character strings in the 'data.frame' be
 #'      coerced to factors?
@@ -15,7 +15,7 @@
 #' @details If you are not interested in the geometries of the results, it's a
 #'      good option to query for objects that match the features only and forget
 #'      about members of the ways and relations. You can achieve this by passing
-#'      the parameter `body = "tags"` to \code{\link{opq}}.
+#'      the parameter `body = "tags"` to [opq()].
 #'
 #' @family extract
 #' @export

R/get-osmdata-sf.R

@@ -1,24 +1,22 @@
-#' Return an OSM Overpass query as an \link{osmdata} object in \pkg{sf}
-#' format.
+#' Return an OSM Overpass query as an [osmdata] object in \pkg{sf} format.
 #'
 #' @note In 'dplyr'-type workflows in which the output of this function is
 #' piped to other functions, it will generally be necessary to explicitly load
 #' the \pkg{sf} package into the current workspace with 'library(sf)'.
 #'
 #' @param q An object of class `overpass_query` constructed with
-#'      \link{opq} and \link{add_osm_feature} or a string with a valid query, such
+#'      [opq()] and [add_osm_feature()] or a string with a valid query, such
 #'      as `"(node(39.4712701,-0.3841326,39.4713799,-0.3839475);); out;"`.
-#'      39.4712701,-0.3841326,39.4713799,-0.3839475
-#'      May be be omitted, in which case the \link{osmdata} object will not
+#'      May be be omitted, in which case the [osmdata] object will not
 #'      include the query. See examples below.
 #' @param doc If missing, `doc` is obtained by issuing the overpass query,
-#'        `q`, otherwise either the name of a file from which to read data,
-#'        or an object of class \pkg{xml2} returned from \link{osmdata_xml}.
+#'      `q`, otherwise either the name of a file from which to read data,
+#'      or an object of class \pkg{xml2} returned from [osmdata_xml()].
 #' @param quiet suppress status messages.
 #' @param stringsAsFactors Should character strings in 'sf' 'data.frame' be
-#' coerced to factors?
-#' @return An object of class `osmdata_sf` with the OSM components (points, lines,
-#'         and polygons) represented in \pkg{sf} format.
+#'      coerced to factors?
+#' @return An object of class `osmdata_sf` with the OSM components (points,
+#'      lines, and polygons) represented in \pkg{sf} format.
 #'
 #' @family extract
 #' @export

R/get-osmdata-sp.R

@@ -1,4 +1,4 @@
-#' DEPRECATED: Return an OSM Overpass query as an \link{osmdata} object in \pkg{sp}
+#' DEPRECATED: Return an OSM Overpass query as an [osmdata] object in \pkg{sp}
 #' format.
 #'
 #' @inheritParams osmdata_sf

R/get-osmdata-xml.R

@@ -3,13 +3,14 @@
 #' or a raw vector.
 #'
 #' @param q An object of class `overpass_query` constructed with
-#'   \link{opq} and \link{add_osm_feature} or a string with a valid query, such
-#'   as `"(node(39.4712701,-0.3841326,39.4713799,-0.3839475);); out;"`. See examples below.
+#'     [opq()] and [add_osm_feature()] or a string with a valid query, such as
+#'     `"(node(39.4712701,-0.3841326,39.4713799,-0.3839475);); out;"`. See
+#'     examples below.
 #' @param filename If given, OSM data are saved to the named file
 #' @param quiet suppress status messages.
 #' @param encoding Unless otherwise specified XML documents are assumed to be
-#'        encoded as UTF-8 or UTF-16. If the document is not UTF-8/16, and lacks
-#'        an explicit encoding directive, this allows you to supply a default.
+#'     encoded as UTF-8 or UTF-16. If the document is not UTF-8/16, and lacks
+#'     an explicit encoding directive, this allows you to supply a default.
 #' @return An object of class `xml2::xml_document` containing the result of the
 #'         overpass API query.
 #'

R/get-osmdata.R

@@ -65,7 +65,7 @@ get_overpass_version <- function (doc) {
 #' implemented for osmdata_* functions except for osmdata_xml (no out:csv) and
 #' osmdata_data_frame.
 #'
-#' @param obj Initial \link{osmdata} object
+#' @param obj Initial [osmdata] object
 #'
 #' @return Nothing. Throw errors or warnings for not implemented queries.
 #'
@@ -147,10 +147,10 @@ fix_columns_list <- function (l) {
 #' fill osmdata object with overpass data and metadata, and return character
 #' version of OSM xml document
 #'
-#' @param obj Initial \link{osmdata} object
+#' @param obj Initial [osmdata] object
 #' @param doc Document contain XML-formatted version of OSM data
 #' @inheritParams osmdata_sf
-#' @return List of an \link{osmdata} object (`obj`), and XML
+#' @return List of an [osmdata] object (`obj`), and XML
 #'      document (`doc`)
 #' @noRd
 fill_overpass_data <- function (obj, doc, quiet = TRUE, encoding = "UTF-8") {

R/getbb.R

@@ -5,7 +5,7 @@
 #' @param bbox bounding box as character, matrix, vector or a data.frame with
 #' `osm_type` and `osm_id` columns.
 #' If character, the bbox will be found (geocoded) and extracted with
-#' \link{getbb}. Unnamed vectors will be sorted appropriately and must merely be
+#' [getbb()]. Unnamed vectors will be sorted appropriately and must merely be
 #' in the order (x, y, x, y).
 #'
 #' @return A character string representing min x, min y, max x, and max y

R/opq.R

@@ -3,13 +3,13 @@
 #' @param bbox Either (i) four numeric values specifying the maximal and minimal
 #'      longitudes and latitudes, in the form \code{c(xmin, ymin, xmax, ymax)}
 #'      or (ii) a character string in the form \code{xmin,ymin,xmax,ymax}. These
-#'      will be passed to \link{getbb} to be converted to a numerical bounding
+#'      will be passed to [getbb()] to be converted to a numerical bounding
 #'      box. Can also be (iii) a matrix representing a bounding polygon as
 #'      returned from `getbb(..., format_out = "polygon")`. To search in an
 #'      area, (iv) a character string with a relation or a (closed) way id in
 #'      the format `"way(id:1)"`, `"relation(id:1, 2)"` or `"relation(id:1, 2,
 #'      3); way(id:2)"` as returned by `getbb(..., format_out = "osm_type_id")`
-#'      or \link{bbox_to_string} with a `data.frame` from `getbb(..., format_out
+#'      or [bbox_to_string()] with a `data.frame` from `getbb(..., format_out
 #'      = "data.frame")` to select all areas combined (relations and ways).
 #' @param nodes_only WARNING: this parameter is equivalent to
 #'      `osm_types = "node"` and is DEPRECATED. If `TRUE`, query OSM nodes
@@ -20,7 +20,7 @@
 #'      `highway = "traffic_signals"` are represented by nodes only. Queries are
 #'      built by default to return all nodes, ways, and relation, but this can
 #'      be very inefficient for node-only queries. Setting this value to `"node"`
-#'      for such cases makes queries more efficient and, in [`osmdata_sf()`], the
+#'      for such cases makes queries more efficient and, in [osmdata_sf()], the
 #'      data will be returned in the `osm_points` list item only.
 #' @param out The level of verbosity of the overpass result: `body` (geometries
 #'      and tags, the default), `tags` (tags without geometry), `meta` (like
@@ -49,9 +49,9 @@
 #' @return An `overpass_query` object
 #'
 #' @details The `out` statement for `tags`, `tags center`and `id`, do not return
-#' geometries. Neither `out = "meta"` nor `adiff = TRUE` options are implemented
-#' for all `osmdata_*` functions yet. Use [osmdata_xml] or [osmdata_data_frame]
-#' to get the result of these queries. See the documentation of the [out
+#' geometries. `adiff = TRUE` option is not implemented for all `osmdata_*` functions yet.
+#' Use [osmdata_xml] or [osmdata_data_frame] to get the result of these queries. See the
+#' documentation of the [out
 #' statement](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#out)
 #' and [augmented
 #' difference](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#Augmented-difference_between_two_dates_(adiff))
@@ -263,24 +263,24 @@ paste_features <- function (key, value, key_pre = "", bind = "=",
 #' not sensitive to case
 #' @param bbox optional bounding box for the feature query; must be set if no
 #'        opq query bbox has been set
-#' @return \link{opq} object
+#' @return An [opq] object.
 #'
 #' @note `key_exact` should generally be `TRUE`, because OSM uses a
 #' reasonably well defined set of possible keys, as returned by
-#' \link{available_features}. Setting `key_exact = FALSE` allows matching
+#' [available_features()]. Setting `key_exact = FALSE` allows matching
 #' of regular expressions on OSM keys, as described in Section 6.1.5 of
 #' <https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL>. The actual
 #' query submitted to the overpass API can be obtained from
-#' \link{opq_string}.
+#' [opq_string()].
 #'
 #' @references <https://wiki.openstreetmap.org/wiki/Map_Features>
-#' @seealso [add_osm_features]
+#' @seealso [add_osm_features()]
 #'
 #' @section `add_osm_feature` vs `add_osm_features`:
-#' Features defined within an [add_osm_features] call are combined with a
+#' Features defined within an [add_osm_features()] call are combined with a
 #' logical OR.
 #'
-#' Chained calls to either [add_osm_feature] or `add_osm_features()` combines
+#' Chained calls to either `add_osm_feature()` or [add_osm_features()] combines
 #' features from these calls in a logical AND; this is analagous to chaining
 #' `dplyr::filter()` on a data frame.
 #'
@@ -478,7 +478,7 @@ check_bind_key_pre <- function (bind = "=", key_pre = "") {
 
 #' Add multiple features to an Overpass query
 #'
-#' Alternative version of \link{add_osm_feature} for creating single queries
+#' Alternative version of [add_osm_feature()] for creating single queries
 #' with multiple features. Key-value matching may be controlled by using the
 #' filter symbols described in
 #' \url{https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#By_tag_.28has-kv.29}.
@@ -491,7 +491,7 @@ check_bind_key_pre <- function (bind = "=", key_pre = "") {
 #'      quotations. See examples for details.
 #' @param bbox optional bounding box for the feature query; must be set if no
 #'      opq query bbox has been set.
-#' @return \link{opq} object
+#' @return An [opq] object.
 #'
 #' @references \url{https://wiki.openstreetmap.org/wiki/Map_Features}
 #' @seealso [add_osm_feature]
@@ -709,7 +709,7 @@ filter_osm_user <- function (opq, user, touched = FALSE, is_uid) {
 #' @param open_url If `TRUE`, open the OSM page of the specified object in web
 #'      browser. Multiple objects (`id` values) will be opened in multiple
 #'      pages.
-#' @return \link{opq} object
+#' @return An [opq] object.
 #'
 #' @references
 #' \url{https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#By_element_id}
@@ -801,8 +801,8 @@ opq_osm_id <- function (id = NULL, type = NULL, open_url = FALSE,
 #'
 #' Find all features which enclose a given point, and optionally match specific
 #' 'key'-'value' pairs. This function is \emph{not} intended to be combined with
-#' \link{add_osm_feature}, rather is only to be used in the sequence
-#' \link{opq_enclosing} -> \link{opq_string} -> \link{osmdata_xml} (or other
+#' [add_osm_feature()], rather is only to be used in the sequence
+#' [opq_enclosing()] -> [opq_string()] -> [osmdata_xml()] (or other
 #' extraction function). See examples for how to use.
 #'
 #' @param lon Longitude of desired point
@@ -868,8 +868,8 @@ opq_enclosing <- function (lon = NULL, lat = NULL,
 #'
 #' Find all features around a given point, and optionally match specific
 #' 'key'-'value' pairs. This function is \emph{not} intended to be combined with
-#' \link{add_osm_feature}, rather is only to be used in the sequence
-#' \link{opq_around} -> \link{osmdata_xml} (or other extraction function). See
+#' [add_osm_feature()], rather is only to be used in the sequence
+#' [opq_around()] -> [osmdata_xml()] (or other extraction function). See
 #' examples for how to use.
 #'
 #' @param radius Radius in metres around the point for which data should be
@@ -920,7 +920,7 @@ opq_around <- function (lon, lat, radius = 15,
 #' Transform an Overpass query to return the result in a csv format
 #'
 #' @param q A opq string or an object of class `overpass_query` constructed with
-#'     \link{opq} or alternative opq builders (+ \link{add_osm_feature}/s).
+#'     [opq()] or alternative opq builders (+ [add_osm_feature()]/s).
 #' @param fields a character vector with the field names.
 #' @param header if \code{FALSE}, do not ask for column names.
 #'
@@ -929,7 +929,7 @@ opq_around <- function (lon, lat, radius = 15,
 #'
 #' @details The output format `csv`, ask for results in csv. See
 #'  [CSV output mode](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#CSV_output_mode)
-#'  for details. To get the data, use \link{osmdata_data_frame}.
+#'  for details. To get the data, use [osmdata_data_frame()].
 #'
 #' @note csv queries that reach the timeout will return a 0 row data.frame
 #'    without any warning. Increase `timeout` in `q` if you don't see the

R/osmdata-package.R

@@ -11,39 +11,39 @@
 #'
 #' @section Functions to Prepare Queries:
 #' \itemize{
-#' \item \link{getbb}: Get bounding box for a given place name
-#' \item \link{bbox_to_string}: Convert a named matrix or a named vector
-#' (or an unnamed vector) return a string
-#' \item \link{overpass_status}: Retrieve status of the overpass API
-#' \item \link{opq}: Build an overpass query
-#' \item \link{add_osm_feature}: Add a feature to an overpass query
-#' \item \link{opq_string}: Convert an osmdata query to overpass API
-#' string
+#' \item [getbb()]: Get bounding box for a given place name
+#' \item [bbox_to_string()]: Convert a named matrix or a named vector (or an
+#'     unnamed vector) return a string
+#' \item [overpass_status()]: Retrieve status of the overpass API
+#' \item [opq()]: Build an overpass query
+#' \item [add_osm_feature()]: Add a feature to an overpass query
+#' \item [add_osm_features()]: Add multiple features to an Overpass query
+#' \item [filter_osm_user()]: Add an user filter to an Overpass query
+#' \item [opq_string()]: Convert an osmdata query to overpass API string
 #' }
 #'
 #' @section Functions to Get Additional OSM Information:
 #' \itemize{
-#' \item \link{available_features}: List recognised features in OSM
-#' \item \link{available_tags}: List tags associated with a feature
+#' \item [available_features()]: List recognised features in OSM
+#' \item [available_tags()]: List tags associated with a feature
 #' }
 #'
 #' @section Functions to Extract OSM Data:
 #' \itemize{
-#' \item \link{osmdata_data_frame}: Return OSM data in \code{\link{data.frame}}
-#'     format
-#' \item \link{osmdata_sc}: Return OSM data in \pkg{silicate} format
-#' \item \link{osmdata_sf}: Return OSM data in \pkg{sf} format
-#' \item \link{osmdata_sp}: Return OSM data in \pkg{sp} format (DEPRECATED)
-#' \item \link{osmdata_xml}: Return OSM data in \pkg{xml2} format
+#' \item [osmdata_data_frame()]: Return OSM data in [`data.frame`] format
+#' \item [osmdata_sc()]: Return OSM data in \pkg{silicate} format
+#' \item [osmdata_sf()]: Return OSM data in \pkg{sf} format
+#' \item [osmdata_sp()]: Return OSM data in \pkg{sp} format (DEPRECATED)
+#' \item [osmdata_xml()]: Return OSM data in \pkg{xml2} format
 #' }
 #'
 #' @section Functions to Search Data:
 #' \itemize{
-#' \item `osm_points`: Extract all `osm_points` objects
-#' \item `osm_lines`: Extract all `osm_lines` objects
-#' \item `osm_polygons`: Extract all `osm_polygons` objects
-#' \item `osm_multilines`: Extract all `osm_multilines` objects
-#' \item `osm_multipolygons`: Extract all `osm_multipolygons` objects
+#' \item [osm_points()]: Extract all `osm_points` objects
+#' \item [osm_lines()]: Extract all `osm_lines` objects
+#' \item [osm_polygons()]: Extract all `osm_polygons` objects
+#' \item [osm_multilines()]: Extract all `osm_multilines` objects
+#' \item [osm_multipolygons()]: Extract all `osm_multipolygons` objects
 #' }
 #'
 #' @docType package

R/trim-osmdata.R

@@ -106,7 +106,7 @@ bb_poly_to_mat <- function (x) {
 #' these methods, but there is no equivalent exported function there. See
 #' \url{https://github.com/r-lib/roxygen2/issues/1592}.
 #'
-#' @param x A bounding-box input to \link{getbb} or \link{opq}.
+#' @param x A bounding-box input to [getbb()] or [opq()].
 #'
 #' @note About the need to export private methods
 #'   github.com/r-lib/roxygen2/issues/1592