Merge pull request #2285 from olivroy/roxygen

Improve documentation

Author: edzer

.github/workflows/tic-db.yml

@@ -5,7 +5,7 @@ on:
   workflow_dispatch:
   push:
     branches:
-      - master
+      - main
   pull_request:
   # for now, CRON jobs only run on the default branch of the repo (i.e. usually on master)
   schedule:

DESCRIPTION

@@ -161,6 +161,7 @@ Collate:
     'gdal_utils.R'
     'nearest.R'
     'normalize.R'
+    'sf-package.R'
     'defunct.R'
     'z_range.R'
     'm_range.R'

PROPOSAL.md

@@ -1,19 +1,19 @@
 # Simple Features for R
 
-Applicant: [Edzer Pebesma](https://github.com/edzer/), [Institute for Geoinformatics](http://ifgi.uni-muenster.de/en), University of Muenster, Germany; [edzer.pebesma@uni-muenster.de](mailto:edzer.pebesma@uni-muenster.de)
+Applicant: [Edzer Pebesma](https://github.com/edzer/), [Institute for Geoinformatics](https://www.uni-muenster.de/Geoinformatics/en/), University of Muenster, Germany; [edzer.pebesma@uni-muenster.de](mailto:edzer.pebesma@uni-muenster.de)
 
 Supporting authors: Edzer Pebesma, Roger Bivand, Michael Sumner, Robert Hijmans, Virgilio Gómez-Rubio
 
-[Simple features](https://en.wikipedia.org/wiki/Simple_Features) is an open ([OGC](http://www.opengeospatial.org/standards/sfa) and [ISO](http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=40114)) interface standard for access and manipulation of spatial vector data (points, lines, polygons). It includes a standard [SQL schema](http://www.opengeospatial.org/standards/sfs) that supports storage, retrieval, query and update of feature collections via a SQL interface. All commonly used databases provide this interface. [GeoJSON](http://geojson.org/) is a standard for encoding simple features in JSON, and is used in JavaScript and MongoDB. Well-known-text ([WKT](https://en.wikipedia.org/wiki/Well-known_text)) is a text representation of simple features used often in linked data; well-known-binary ([WKB] (https://en.wikipedia.org/wiki/Well-known_text)) a standard binary representation used in databases. _Simple Feature Access_ defines coordinate reference systems, and makes it easy to move data from longitude-latitude to projections back and forth in a standardized way. 
+[Simple features](https://en.wikipedia.org/wiki/Simple_Features) is an open ([OGC](https://www.ogc.org/standard/sfa/) and [ISO](https://www.iso.org/standard/40114.html)) interface standard for access and manipulation of spatial vector data (points, lines, polygons). It includes a standard [SQL schema](http://www.opengeospatial.org/standards/sfs) that supports storage, retrieval, query and update of feature collections via a SQL interface. All commonly used databases provide this interface. [GeoJSON](https://geojson.org/) is a standard for encoding simple features in JSON, and is used in JavaScript and MongoDB. Well-known-text ([WKT](https://en.wikipedia.org/wiki/Well-known_text)) is a text representation of simple features used often in linked data; well-known-binary ([WKB] (https://en.wikipedia.org/wiki/Well-known_text)) a standard binary representation used in databases. _Simple Feature Access_ defines coordinate reference systems, and makes it easy to move data from longitude-latitude to projections back and forth in a standardized way. 
 
 
-[GDAL](http://gdal.org/) is an open source C++ library for reading and writing both raster and vector data with more than 225 drivers (supported file formats, data base connectors, web service interfaces). GDAL is used by practically all open source geospatial projects and by many industry products (including ESRI's ArcGIS, ERDAS, and FME). It provides coordinate transformations (built on top of PROJ.4) and geometric operations (e.g. polygon intersections, unions, buffers and distance). Standards for coordinate transformations change over time; such changes are typically adopted directly in GDAL/PROJ.4 but do not easily find their way into R-only packages such as `mapproj`.
+[GDAL](https://gdal.org/) is an open source C++ library for reading and writing both raster and vector data with more than 225 drivers (supported file formats, data base connectors, web service interfaces). GDAL is used by practically all open source geospatial projects and by many industry products (including ESRI's ArcGIS, ERDAS, and FME). It provides coordinate transformations (built on top of PROJ.4) and geometric operations (e.g. polygon intersections, unions, buffers and distance). Standards for coordinate transformations change over time; such changes are typically adopted directly in GDAL/PROJ.4 but do not easily find their way into R-only packages such as `mapproj`.
 
-Since [2005](https://stat.ethz.ch/pipermail/r-sig-geo/2005-April/000378.html), CRAN has package [sp](https://cran.r-project.org/web/packages/sp/) which provides classes and methods for spatial (point, line, polygon and raster) data. The approach `sp` takes is similar to how `xts` and `zoo` handle the time index of time series data: objects store spatial geometries separately from associated attribute data, matching by order. Package [spacetime](https://cran.r-project.org/web/packages/spacetime/index.html), on CRAN since 2010, extends both `sp` and `xts` to handle data that varies over both space and time.
+Since [2005](https://stat.ethz.ch/pipermail/r-sig-geo/2005-April/000378.html), CRAN has package [sp](https://cran.r-project.org/package=sp) which provides classes and methods for spatial (point, line, polygon and raster) data. The approach `sp` takes is similar to how `xts` and `zoo` handle the time index of time series data: objects store spatial geometries separately from associated attribute data, matching by order. Package [spacetime](https://cran.r-project.org/package=spacetime), on CRAN since 2010, extends both `sp` and `xts` to handle data that varies over both space and time.
 
-Today, 221 CRAN packages depend on, import or link to `sp`, 259 when including _Suggests_; when including recursive dependencies these numbers are 376 and 5040. The implementation of `sp` does not follow simple features, but rather the practice used at the time of release, following how ESRI shapefiles are implemented. The cluster of packages around `sp` is shown in Andrie de Vries' [blog on CRAN's network structure](http://blog.revolutionanalytics.com/2015/07/the-network-structure-of-cran.html) in green.
+Today, 221 CRAN packages depend on, import or link to `sp`, 259 when including _Suggests_; when including recursive dependencies these numbers are 376 and 5040. The implementation of `sp` does not follow simple features, but rather the practice used at the time of release, following how ESRI shapefiles are implemented. The cluster of packages around `sp` is shown in Andrie de Vries' [blog on CRAN's network structure](https://blog.revolutionanalytics.com/2015/07/the-network-structure-of-cran.html) in green.
 
-Off-CRAN package [rgdal2](https://github.com/thk686/rgdal2) is an interface to GDAL 2.0, which uses raw pointers to interface features, but does not import any data in R, using GDAL to handle everything. CRAN Package [wkb](https://cran.r-project.org/web/packages/wkb/index.html), contributed by Tibco Software, converts between WKB representations of several simple feature classes and corresponding classes in `sp`, and seems to be needed for Tibco software purposes.
+Off-CRAN package [rgdal2](https://github.com/thk686/rgdal2) is an interface to GDAL 2.0, which uses raw pointers to interface features, but does not import any data in R, using GDAL to handle everything. CRAN Package [wkb](https://cran.r-project.org/package=wkb), contributed by Tibco Software, converts between WKB representations of several simple feature classes and corresponding classes in `sp`, and seems to be needed for Tibco software purposes.
 
 <!---
 [second edition](http://www.springer.com/statistics/life+sciences%2C+medicine+%26+health/book/978-1-4614-7617-7))
@@ -24,14 +24,14 @@ Off-CRAN package [rgdal2](https://github.com/thk686/rgdal2) is an interface to G
 The problems we will solve are:
 
 1. R can currently not represent simple features directly. It can read most simple feature classes in `sp` classes, but uses its own representation for this, and can only write data back without loss of information if it is furnished with ancilliary metadata encoded in a comment attribute to each Polygons object. It does for instance internally not distinguish between `POLYGON` and `MULTIPOLYGON`  nor deal with several simple feature classes, including `TIN` and `GEOMETRYCOLLECTION`, nor handle `CURVE` geometries.
-2. The current implementation of lines and vector data in package `sp` is partly ambiguous (both slot `ringDir` or slot `hole` indicate whether a Polygon is a hole but are superceded by the comment attribute), complicated (to which exterior polygon does a hole belong - handled by the comment attribute), and by some considered difficult to work with (S4). The current implementation is hard to maintain because it contains incremental changes from a baseline that predated the industry-standard OGC/ISO ([Simple Feature Interface Specification](http://www.opengeospatial.org/standards/sfa)).
+2. The current implementation of lines and vector data in package `sp` is partly ambiguous (both slot `ringDir` or slot `hole` indicate whether a Polygon is a hole but are superceded by the comment attribute), complicated (to which exterior polygon does a hole belong - handled by the comment attribute), and by some considered difficult to work with (S4). The current implementation is hard to maintain because it contains incremental changes from a baseline that predated the industry-standard OGC/ISO ([Simple Feature Interface Specification](https://www.ogc.org/standard/sfa/)).
 3. The lack of support for simple features makes current interfaces to open source libraries (GDAL/OGR and PROJ.4: rgdal, GEOS: rgeos) difficult to understand and maintain, even though they work to specification.
-4. The current implementation has no [scale model](http://geos.osgeo.org/doxygen/classgeos_1_1geom_1_1PrecisionModel.html#details) for coordinates.
+4. The current implementation has no [scale model](https://libgeos.org/doxygen/classgeos_1_1geom_1_1PrecisionModel.html#details) for coordinates.
 5. It is desirable that other R packages are offered the opportunity to migrate to more up-to-date libraries for coordinate transformations (providing proper support for datum transformation), and to avoid having to make simplifying assumptions (e.g., all spatial data come as longitude/latitude using datum `WGS84`; all web maps use [_web Mercator_](https://en.wikipedia.org/wiki/Web_Mercator)).
 
 Which users will benefit from solving these problems?  It will mainly affect those who use data bases or modern javascript-based web APIs which largely converged on adopting simple features (such as [CartoDB](https://cartodb.com/)), as well as those who need a simpler and more light-weight handling of spatial data in R. It will also reduce the effort for users and developers to understand the way spatial information is represented in R, making it easier to build upon and reuse the R code for this, and lead to a good, sustainable shared R code base.
 
-In the longer run it will affect users of all packages currently reusing `sp` classes, when we manage to migrate `sp` to exclusively use the simple feature classes for representing vector data. Since the recent [2.0](http://www.gdal.org/index.html) release of GDAL integrates raster and vector data, having an R package that mirrors its classes makes it possible to implement operations in-database (similar to what `DBI`, `RPostgreSQL` and `dplyr` do), making it possible for R to manipulate spatial data that do not fit in memory.
+In the longer run it will affect users of all packages currently reusing `sp` classes, when we manage to migrate `sp` to exclusively use the simple feature classes for representing vector data. Since the recent [2.0](https://gdal.org/index.html) release of GDAL integrates raster and vector data, having an R package that mirrors its classes makes it possible to implement operations in-database (similar to what `DBI`, `RPostgreSQL` and `dplyr` do), making it possible for R to manipulate spatial data that do not fit in memory.
 
 Big Data analysis with R often proceeds by connecting R to a database that holds the data. All commonly used commercial and open source databases store spatial point, line and polygon data in the form of simple features. Representing simple features in R will simplify big data analysis for spatial data.
 
@@ -73,8 +73,8 @@ The visit of Roger is anticipated halfway the project; further communications wi
 
 ## Dissemination
 
-Development will take place on github, information will be shared and reactions and contributions invited through [r-sig-geo](https://stat.ethz.ch/mailman/listinfo/r-sig-geo), as well as [StackOverflow](http://stackoverflow.com/) and [GIS StackExchange](http://gis.stackexchange.com/). The project will use an Apache 2.0 license for maximum dissemination (similar to GDAL, which uses X/MIT). The work will be published in 4 blogs (quarterly), announced on r-sig-geo (3300 subscribers), and intermediary results will be presented at [UseR! 2016](http://user2016.org/). The final result will be published in a paper either submitted to [The R Journal](https://journal.r-project.org/) or to the [Journal of Statistical Software](http://www.jstatsoft.org/); this paper will be available before publication as a package vignette.
+Development will take place on github, information will be shared and reactions and contributions invited through [r-sig-geo](https://stat.ethz.ch/mailman/listinfo/r-sig-geo), as well as [StackOverflow](https://stackoverflow.com/) and [GIS StackExchange](https://gis.stackexchange.com/). The project will use an Apache 2.0 license for maximum dissemination (similar to GDAL, which uses X/MIT). The work will be published in 4 blogs (quarterly), announced on r-sig-geo (3300 subscribers), and intermediary results will be presented at [UseR! 2016](https://www.r-project.org/conferences/useR-2016/). The final result will be published in a paper either submitted to [The R Journal](https://journal.r-project.org/) or to the [Journal of Statistical Software](https://www.jstatsoft.org/index); this paper will be available before publication as a package vignette.
 
 ## UseR! slides
 
-UseR! 2016 slides are found [here](http://pebesma.staff.ifgi.de/pebesma_sfr.pdf).
+UseR! 2016 slides are found [here](https://pebesma.staff.ifgi.de/pebesma_sfr.pdf).

R/datasets.R

@@ -6,9 +6,12 @@
 #' though this is basically the same as \code{nc.sids} dataset in spData
 #' package, \code{nc} only contains a subset of variables. The differences are
 #' also discussed on the vignette.
-#'
+#' @format A `sf` object 
 #' @name nc
 #' @docType data
-#' @keywords data
 #' @seealso \url{https://r-spatial.github.io/spdep/articles/sids.html}
+#' @examples
+#' \donttest{
+#' nc <- st_read(system.file("shape/nc.shp", package="sf"))
+#' }
 NULL

R/defunct.R

@@ -1,10 +1,11 @@
-#' Deprecated functions in `sf`
-#'
-#' These functions are provided for compatibility with older version of `sf`.
-#' They may eventually be completely removed.
-#' @md
-#' @rdname sf-defunct
+#' @title Deprecated functions in `sf`
 #' @name sf-defunct
+#' @description
+#' These functions are provided for compatibility with older version of `sf`.
+#' They will eventually be completely removed.
+#' 
+#' * Use [st_read()] instead of `st_read_db()`.
+#' * Use [st_write()] instead_of `st_write_db()`
 #' @param conn open database connection
 #' @param table table name
 #' @param geom_column deprecated. Geometry column name
@@ -13,21 +14,15 @@
 #' it will try to cast all the character columns, which can be long for very wide
 #' tables.
 #' @inheritParams st_read
-#' @export  st_read_db st_write_db
-#' @aliases st_read_db, st_write_db
-#' @section Details:
-#' \tabular{rl}{
-#'   \code{st_read_db} \tab now a synonym for \code{\link{st_read}}\cr
-#'   \code{st_write_db} \tab now a synonym for \code{\link{st_write}}\cr
-#' }
-#'
 #' @export
+#' @keywords internal
 st_read_db <- function(conn = NULL, table = NULL, query = NULL,
 					   geom_column = NULL, EWKB = TRUE, ...) {
 	.Defunct("st_read")
 }
 
-#' @inheritDotParams dbWriteTable
+#' @rdname sf-defunct
+#' @inheritParams DBI::dbWriteTable
 #' @export
 st_write_db <- function(conn = NULL, obj, table = deparse(substitute(obj)), ...,
 						drop = FALSE, append = FALSE) {

R/geom-predicates.R

@@ -114,7 +114,7 @@ st_relate	= function(x, y, pattern = NA_character_, sparse = !is.na(pattern)) {
 #' @param x object of class \code{sf}, \code{sfc} or \code{sfg}
 #' @param y object of class \code{sf}, \code{sfc} or \code{sfg}; if missing, \code{x} is used
 #' @param sparse logical; should a sparse index list be returned (TRUE) or a dense logical matrix? See below.
-#' @param ... passed on to \link[s2]{s2_options}
+#' @inheritDotParams s2::s2_options
 #' @param prepared logical; prepare geometry for x, before looping over y? See Details.
 #' @details If \code{prepared} is \code{TRUE}, and \code{x} contains POINT geometries and \code{y} contains polygons, then the polygon geometries are prepared, rather than the points.
 #' @return If \code{sparse=FALSE}, \code{st_predicate} (with \code{predicate} e.g. "intersects") returns a dense logical matrix with element \code{i,j} \code{TRUE} when \code{predicate(x[i], y[j])} (e.g., when geometry of feature i and j intersect); if \code{sparse=TRUE}, an object of class \code{\link{sgbp}} with a sparse list representation of the same matrix, with list element \code{i} an integer vector with all indices j for which \code{predicate(x[i],y[j])} is \code{TRUE} (and hence a zero-length integer vector if none of them is \code{TRUE}). From the dense matrix, one can find out if one or more elements intersect by \code{apply(mat, 1, any)}, and from the sparse list by \code{lengths(lst) > 0}, see examples below.

R/geom-transformers.R

@@ -1111,7 +1111,7 @@ st_line_sample = function(x, n, density, type = "regular", sample = NULL) {
 }
 
 #' Internal functions
-#' @name internal
+#' @keywords internal
 #' @param msg error message
 #' @export
 .stop_geos = function(msg) { #nocov start

R/plot.R

@@ -710,8 +710,8 @@ get_asp = function(bb) {
 	asp
 }
 
-
-#' @export
+#' functions only exported to be used internally by stars
+#' @keywords internal
 #' @name stars
 #' @param bb ignore
 #' @param n ignore
@@ -720,6 +720,7 @@ get_asp = function(bb) {
 #' @param key.length ignore
 #' @param mfrow length-2 integer vector with number of rows, columns
 #' @param main main or sub title
+#' @export
 .get_layout = function(bb, n, total_size, key.pos, key.width, mfrow = NULL, main = NULL) {
 # return list with "m" matrix, "key.pos", "widths" and "heights" fields
 # if key.pos = -1 on input, it will be a return value, "optimally" placed
@@ -796,16 +797,15 @@ bb2merc = function(x, cls = "ggmap") { # return bbox in the appropriate "web mer
 	st_bbox(st_transform(pts, merc))
 }
 
-#' functions only exported to be used internally by stars
-#' @name stars
-#' @export
+#' @rdname stars
 #' @param side ignore
 #' @param at ignore
 #' @param labels ignore
 #' @param lon ignore
 #' @param lat ignore
 #' @param ndiscr ignore
 #' @param reset ignore
+#' @export
 .degAxis = function (side, at, labels, ..., lon, lat, ndiscr, reset) {
 	if (missing(at))
        	at = axTicks(side)
@@ -838,8 +838,7 @@ xy_from_r = function(r, l, o) {
 	c(x, y)
 }
 
-#' @name stars
-#' @export
+#' @rdname stars
 #' @param z ignore
 #' @param col ignore
 #' @param breaks ignore
@@ -850,6 +849,7 @@ xy_from_r = function(r, l, o) {
 #' @param ... ignore
 #' @param lab ignore
 #' @param cex.axis see \link{par}
+#' @export
 .image_scale = function(z, col, breaks = NULL, key.pos, add.axis = TRUE,
 		at = NULL, ..., axes = FALSE, key.length, logz = FALSE, lab = "", 
 		cex.axis = par("cex.axis")) {
@@ -929,9 +929,9 @@ xy_from_r = function(r, l, o) {
 		axis(key.pos, at = at, labels = labels, cex.axis = cex.axis)
 }
 
-#' @name stars
-#' @export
+#' @rdname stars
 #' @param key.width ignore
+#' @export
 .image_scale_factor = function(z, col, key.pos, add.axis = TRUE,
 	..., axes = FALSE, key.width, key.length, cex.axis = par("cex.axis")) {