docs: Improve website + group articles + tweaks to documentation (#903)

.Rbuildignore

@@ -33,5 +33,5 @@
 ^revdep$
 ^CRAN-SUBMISSION$
 ^_dev$
-^vignettes$
+^vignettes/articles$
 ^pkgdown$

.github/CONTRIBUTING.md

@@ -1,4 +1,6 @@
-We welcome contributions to the **leaflet** package!
+# Contributing to `{leaflet}`
+
+We welcome contributions to the `{leaflet}` package!
 
 To submit a contribution:
 

.github/ISSUE_TEMPLATE.md

@@ -1,6 +1,6 @@
-Please briefly describe your problem and what output you expect. If you have a question, please try using stackoverflow <http://stackoverflow.com> first.
+Please briefly describe your problem and what output you expect. If you have a question, please try using StackOverflow <https://stackoverflow.com> first.
 
-Please include a minimal reprex. The goal of a reprex is to make it as easy as possible for me to recreate your problem so that I can fix it. If you've never heard of a reprex before, start by reading <https://github.com/jennybc/reprex#what-is-a-reprex>, and follow the advice further down the page. Do NOT include session info unless it's explicitly asked for, or you've used `reprex::reprex(..., si = TRUE)` to hide it away.  Make sure to have `webshot` installed to have `reprex` produces images of the leaflet htmlwidgets.
+Please include a minimal reprex. The goal of a reprex is to make it as easy as possible for me to recreate your problem so that I can fix it. If you've never heard of a reprex before, start by reading <https://reprex.tidyverse.org/>, and follow the advice further down the page. Do NOT include session info unless it's explicitly asked for, or you've used `reprex::reprex(..., session_info = TRUE)` to hide it away.  Make sure to have `webshot` installed to have `reprex` produces images of the leaflet htmlwidgets.
 ```r
 # make sure webshot is installed to take pictures of htmlwidgets
 if (!("webshot" %in% installed.packages()[, "Package"])) {

.github/PULL_REQUEST_TEMPLATE.md

@@ -21,7 +21,7 @@ We will try to be responsive and provide feedback in case we decide not to merge
 
 ## Minimal reproducible example
 
-Finally, please include a minimal reprex. The goal of a reprex is to make it as easy as possible for me to recreate your problem so that I can fix it. If you've never heard of a reprex before, start by reading <https://github.com/jennybc/reprex#what-is-a-reprex>, and follow the advice further down the page. Do NOT include session info unless it's explicitly asked for, or you've used `reprex::reprex(..., si = TRUE)` to hide it away.  Make sure to have `webshot` installed to have `reprex` produces images of the leaflet htmlwidgets.
+Finally, please include a minimal reprex. The goal of a reprex is to make it as easy as possible for me to recreate your problem so that I can fix it. If you've never heard of a reprex before, start by reading <https://reprex.tidyverse.org/>, and follow the advice further down the page. Do NOT include session info unless it's explicitly asked for, or you've used `reprex::reprex(..., session_info = TRUE)` to hide it away.  Make sure to have `webshot` installed to have `reprex` produces images of the leaflet htmlwidgets.
 ```r
 # make sure webshot is installed to take pictures of htmlwidgets
 if (!("webshot" %in% installed.packages()[, "Package"])) {

NEWS.md

@@ -52,7 +52,7 @@
 
 - Enable JS function literals (wrapped in `htmlwidgets::JS()`) to be included in arguments to methods invoked on `leafletProxy` objects. (JS function literals could already be included with methods invoked on `leaflet` objects, so this change just brings `leafletProxy` to parity.) (#420)
 
-- Add missing CSS rule to show `<img>` in right-pane and left-pane (rstudio/rmarkdown/issues#1949, #770)
+- Add missing CSS rule to show `<img>` in right-pane and left-pane (rstudio/rmarkdown#1949, #770)
 
 - Allow for _hidden_ but not suspended leaflet maps to queue calls (such as add raster images) until they are rendered. If a new leaflet map is created, all pending calls are removed. (#771)
 
@@ -137,7 +137,7 @@
 
 ## Bug fixes and features
 
-- Relative protocols are used where possible when adding tiles (#526). In RStudio 1.1.x on linux and windows, a known issue of 'https://' routes fail to load, but works within browsers (rstudio/rstudio#2661).
+- Relative protocols are used where possible when adding tiles (#526). In RStudio 1.1.x on Linux and Windows, a known issue of 'https://' routes fail to load, but works within browsers (rstudio/rstudio#2661).
 
 - Added more providers for `addProviderTiles()`: "OpenStreetMap.CH", "OpenInfraMap", "OpenInfraMap.Power", "OpenInfraMap.Telecom", "OpenInfraMap.Petroleum", "OpenInfraMap.Water", "OpenPtMap", "OpenRailwayMap", "OpenFireMap", "SafeCast". (4aea447)
 
@@ -221,7 +221,7 @@
 - When used with `leafletProxy`, `fitBounds` did not return its input object as
   output, so magrittr chains would break after `fitBounds` was called.
 
-- Add addMeasure()/removeMeasure() functions to allow users to measure lines and
+- Add `addMeasure()`/`removeMeasure()` functions to allow users to measure lines and
   areas, via the leaflet-measure plugin by @ljagis. (PR #171. Thanks, Kenton
   Russell!)
 

R/layers.R

@@ -1,7 +1,9 @@
 #' Evaluate list members that are formulae, using the map data as the environment
-#' (if provided, otherwise the formula environment)
+#'
+#' Evaluates if provided. Otherwise, the formula environment is evaluated.
 #' @param list with members as formulae
 #' @param data map data
+#' @keywords internal
 #' @export
 evalFormula <- function(list, data) {
   evalAll <- function(x) {
@@ -44,7 +46,9 @@ expandLimits <- function(map, lat, lng) {
   map
 }
 
-#' Same as expandLimits, but takes a polygon (that presumably has a bbox attr)
+#' Notifies the map of polygons of interest on the map
+#'
+#' Same as `expandLimits()`, but takes a polygon (that presumably has a bbox attr)
 #' rather than lat/lng.
 #' @param map map object
 #' @param poly A spatial object representing a polygon.
@@ -1213,7 +1217,7 @@ markerOptions <- function(
 #'   \code{\{weight: 1.5, color: "#222", opacity: 0.5 \}}.
 #' @param freezeAtZoom Allows you to freeze cluster expansion to a zoom level.
 #'   Can be a zoom level e.g. 10, 12 or "max" or "maxKeepSpiderify".
-#'   See <https://github.com/ghybs/Leaflet.MarkerCluster.Freezable#api-reference>.
+#'   See \url{https://github.com/ghybs/Leaflet.MarkerCluster.Freezable#api-reference}.
 #' @describeIn map-options Options for marker clusters
 #' @export
 markerClusterOptions <- function(

R/leaflet-package.R

@@ -1,12 +1,9 @@
 #' @keywords internal
-#' @aliases leaflet-package NULL
 "_PACKAGE"
 
 ## usethis namespace: start
 #' @importFrom grDevices col2rgb
 #' @importFrom grDevices rgb
-#' @importFrom htmlwidgets JS
-#' @importFrom magrittr %>%
 #' @importFrom methods substituteDirect
 #' @importFrom stats na.omit
 #' @importFrom stats quantile
@@ -16,9 +13,12 @@
 NULL
 
 ## Re-exports
-#' @export %>%
-#' @export JS
-NULL
+#' @importFrom magrittr %>%
+#' @export
+magrittr::`%>%`
+#' @importFrom htmlwidgets JS
+#' @export
+htmlwidgets::JS
 
 # Added to the `use_release_issue()` checklist
 release_bullets <- function() {

R/leaflet.R

@@ -103,8 +103,9 @@ hookWrapperTemplate <- "function(el, x, data) {
   return (%s).call(this.getMap(), el, x, data);
 }"
 
-#' returns the map's data
+#' Extract the map's data
 #' @param map the map
+#' @returns The map's data
 #' @export
 getMapData <- function(map) {
   attr(map$x, "leafletData", exact = TRUE)

R/normalize.R

@@ -35,16 +35,22 @@ metaData.data.frame <- function(obj) obj
 metaData.list <- function(obj) obj
 
 
-#' Given a data object and lng/lat arguments (which may be NULL [meaning infer
-#' from data], formula [which should be evaluated with respect to the data], or
+#' Normalize data to a data frame or Spatial object.
+#'
+#' Given a data object and lng/lat arguments (which may be `NULL`)
+#' [meaning infer from data], formula [which should be evaluated with respect to the data], or
 #' vector data [which should be used as-is]) return a lng/lat data frame.
+#'
 #' @param data map data
-#' @param lng longitude
-#' @param lat latitude
+#' @param lng,lat longitude and latitude
 #' @param missingLng whether lng is missing
 #' @param missingLat whether lat is missing
 #' @param funcName Name of calling function (for logging)
+#' @returns
+#' * `derivePoints()` returns a lng/lat data frame.
+#' * `derivePolygons()` returns a list with bbox attributes.
 #' @export
+#' @keywords internal
 derivePoints <- function(data, lng = NULL, lat = NULL,
                          missingLng = missing(lng),
                          missingLat = missing(lat),
@@ -65,15 +71,7 @@ derivePoints <- function(data, lng = NULL, lat = NULL,
   validateCoords(lng, lat, funcName)
 }
 
-#' Given a data object and lng/lat arguments (which may be NULL [meaning infer
-#' from data], formula [which should be evaluated with respect to the data], or
-#' vector data [which should be used as-is]) return a spatial object
-#' @param data map data
-#' @param lng longitude
-#' @param lat latitude
-#' @param missingLng whether lng is missing
-#' @param missingLat whether lat is missing
-#' @param funcName Name of calling function (for logging)
+#' @rdname derivePoints
 #' @export
 derivePolygons <- function(data, lng = NULL, lat = NULL,
                            missingLng = missing(lng),

R/plugin-awesomeMarkers.R

@@ -159,13 +159,13 @@ makeAwesomeIcon <- function(
   structure(icon, class = "leaflet_awesome_icon")
 }
 
-#' Create a list of awesome icon data see
-#' \url{https://github.com/lennardv2/Leaflet.awesome-markers}
+#' Create a list of awesome icon data
 #'
 #' An icon can be represented as a list of the form \code{list(icon, library,
 #' ...)}. This function is vectorized over its arguments to create a list of
-#' icon data. Shorter argument values will be re-cycled. \code{NULL} values for
-#' these arguments will be ignored.
+#' icon data. Shorter argument values will be recycled. \code{NULL} values for
+#' these arguments will be ignored. 
+#' @seealso \url{https://github.com/lennardv2/Leaflet.awesome-markers}
 #' @param icon Name of the icon
 #' @param library Which icon library. Default \code{"glyphicon"}, other possible
 #'   values are \code{"fa"} (fontawesome) or \code{"ion"} (ionicons).

R/plugin-graticule.R

@@ -11,11 +11,11 @@ leafletGraticuleDependencies <- function() {
 }
 
 #' Add a Graticule on the map
-#' see \url{https://github.com/turban/Leaflet.Graticule}
 #'
+#' @seealso \url{https://github.com/turban/Leaflet.Graticule}
 #' @param map a map widget object
 #' @param interval The spacing in map units between horizontal and vertical lines.
-#' @param sphere boolean. Default FALSE
+#' @param sphere boolean. Default `FALSE`
 #' @param style path options for the generated lines. See \url{https://web.archive.org/web/20220702182250/https://leafletjs.com/reference-1.3.4.html#path-option}
 #' @param layerId the layer id
 #' @param group the name of the group this layer belongs to.

R/plugin-minimap.R

@@ -13,13 +13,13 @@ leafletMiniMapDependencies <- function() {
   )
 }
 
-#' Add a minimap to the Map
-#' \url{https://github.com/Norkart/Leaflet-MiniMap}
+#' Add a minimap to the map
 #'
+#' @seealso \url{https://github.com/Norkart/Leaflet-MiniMap}
 #' @param map a map widget object
 #' @param position The standard Leaflet.Control position parameter,
 #'    used like all the other controls.
-#' Defaults to "bottomright".
+#'    Defaults to `"bottomright"`.
 #' @param width  The width of the minimap in pixels. Defaults to 150.
 #' @param height The height of the minimap in pixels. Defaults to 150.
 #' @param collapsedWidth The width of the toggle marker and the minimap
@@ -39,7 +39,7 @@ leafletMiniMapDependencies <- function() {
 #' @param zoomAnimation Sets whether the minimap should have an animated zoom.
 #'    (Will cause it to lag a bit after the movement of the main map.)
 #'    Defaults to false.
-#' @param toggleDisplay Sets whether the minimap should have a button to minimise it.
+#' @param toggleDisplay Sets whether the minimap should have a button to minimize it.
 #'    Defaults to false.
 #' @param autoToggleDisplay Sets whether the minimap should hide automatically,
 #'    if the parent map bounds does not fit within the minimap bounds.

R/plugin-simplegraticule.R

@@ -12,15 +12,14 @@ leafletSimpleGraticuleDependencies <- function() {
 }
 
 #' Add a simple Graticule on the map
-#' see \url{https://github.com/ablakey/Leaflet.SimpleGraticule}
 #'
+#' @seealso \url{https://github.com/ablakey/Leaflet.SimpleGraticule}
 #' @param map a map widget object
 #' @param interval The spacing in map units between horizontal and vertical lines.
 #' @param showOriginLabel  true Whether or not to show '(0,0)' at the origin.
-#' @param redraw on which map event to redraw the graticule. On move is default but moveend can be smoother.
+#' @param redraw on which map event to redraw the graticule. On move is default but `"moveend"` can be smoother.
 #' @param hidden hide on start
 #' @param zoomIntervals use different intervals in different zoom levels. If not specified, all zoom levels use value in interval option.
-
 #' @param layerId the layer id
 #' @param group the name of the group this layer belongs to.
 #' @examples

R/utils.R

@@ -34,9 +34,11 @@ dispatch <- function(map,
     stop("Invalid map parameter")
 }
 
-#' remove NULL elements from a list
-#' @param x A list whose NULL elements will be filtered
+#' Remove NULL elements from a list
+#' @param x A list.
 #' @export
+#' @returns A list with `NULL` elements filtered out.
+#' @keywords internal
 filterNULL <- function(x) {
   if (length(x) == 0 || !is.list(x)) return(x)
   x[!unlist(lapply(x, is.null))]

inst/examples/awesomeMarkers.R

@@ -33,7 +33,7 @@ leaflet() %>% addTiles() %>%
   addAwesomeMarkers(
     lng = -118.456554, lat = 34.078039,
     label = "This is a static label",
-    labelOptions = labelOptions(noHide = T),
+    labelOptions = labelOptions(noHide = TRUE),
     icon = icon.fa)
 
 
@@ -75,5 +75,5 @@ popIcons <- awesomeIconList(
 leaflet(cities) %>% addProviderTiles(providers$CartoDB.DarkMatter) %>%
   addAwesomeMarkers(lng = ~Long, lat = ~Lat,
              label = ~City,
-             labelOptions = rep(labelOptions(noHide = T), nrow(cities)),
+             labelOptions = rep(labelOptions(noHide = TRUE), nrow(cities)),
              icon = ~popIcons[PopCat] )

inst/examples/labels.R

@@ -12,7 +12,7 @@ leaflet() %>% addTiles() %>%
   addMarkers(
     lng = -118.456554, lat = 34.078039,
     label = "This is a static label",
-    labelOptions = labelOptions(noHide = T))
+    labelOptions = labelOptions(noHide = TRUE))
 #' <br/><br/>
 
 # Circle Marker + Label in all 4 directions.
@@ -24,23 +24,23 @@ leaflet() %>% addTiles() %>%
   addCircleMarkers(
     lng = -118.45990, lat = 34.078079, radius = 5,
     label = "On the Right",
-    labelOptions = labelOptions(noHide = T, direction = "right")
+    labelOptions = labelOptions(noHide = TRUE, direction = "right")
   ) %>%
   addCircleMarkers(
     lng = -118.45280, lat = 34.078079, radius = 5,
     label = "On the left",
-    labelOptions = labelOptions(noHide = T, direction = "left")
+    labelOptions = labelOptions(noHide = TRUE, direction = "left")
   ) %>%
   addCircleMarkers(
     lng = -118.456554, lat = 34.079979, radius = 5,
     label = "On the Top",
-    labelOptions = labelOptions(noHide = T, direction = "top",
+    labelOptions = labelOptions(noHide = TRUE, direction = "top",
                                 offset = c(0, -15))
   ) %>%
   addCircleMarkers(
     lng = -118.456554, lat = 34.076279, radius = 5,
     label = "On the Bottom",
-    labelOptions = labelOptions(noHide = T, direction = "bottom",
+    labelOptions = labelOptions(noHide = TRUE, direction = "bottom",
                                 offset = c(0, 15)))
 #' <br/><br/>
 
@@ -50,19 +50,19 @@ leaflet() %>% addTiles() %>% setView(-118.456554, 34.09, 13) %>%
   addMarkers(
     lng = -118.456554, lat = 34.07,
     label = "Default Label",
-    labelOptions = labelOptions(noHide = T)) %>%
+    labelOptions = labelOptions(noHide = TRUE)) %>%
   addMarkers(
     lng = -118.456554, lat = 34.085,
     label = "Label w/o surrounding box",
-    labelOptions = labelOptions(noHide = T, textOnly = TRUE)) %>%
+    labelOptions = labelOptions(noHide = TRUE, textOnly = TRUE)) %>%
   addMarkers(
     lng = -118.456554, lat = 34.095,
     label = "label w/ textsize 15px",
-    labelOptions = labelOptions(noHide = T, textsize = "15px")) %>%
+    labelOptions = labelOptions(noHide = TRUE, textsize = "15px")) %>%
   addMarkers(
     lng = -118.456554, lat = 34.11,
     label = "Label w/ custom CSS style",
-    labelOptions = labelOptions(noHide = T, textOnly = FALSE,
+    labelOptions = labelOptions(noHide = TRUE, textOnly = FALSE,
                                 style = list(
                                   "color" = "red",
                                   "font-family" = "serif",
@@ -126,7 +126,7 @@ leaflet(cities) %>% addTiles() %>%
   addCircleMarkers(lng = ~Long, lat = ~Lat,
              label = ~City,
              labelOptions = lapply(1:nrow(cities), function(x) {
-               labelOptions(opacity = 1, noHide = T,
+               labelOptions(opacity = 1, noHide = TRUE,
                             direction = "auto", offset = c(20, -15))
              }))
 #' <br/><br/>
@@ -139,7 +139,7 @@ leaflet(cities) %>% addTiles() %>%
                function(x, y) {
                  HTML(sprintf("<em>%s:</em> %s", htmlEscape(x), htmlEscape(y)))
                },
-               cities$City, cities$Pop, SIMPLIFY = F),
+               cities$City, cities$Pop, SIMPLIFY = FALSE),
              labelOptions = lapply(1:nrow(cities), function(x) {
                labelOptions(direction = "auto")
              }))

inst/examples/marker-clustering.R

@@ -24,7 +24,7 @@ l %>%
                       lng = ~long, lat = ~lat,
                       label = ~as.character(mag),
                       clusterOptions = markerClusterOptions(),
-                      labelOptions = labelOptions(noHide = T,
+                      labelOptions = labelOptions(noHide = TRUE,
                                                   direction = "auto"))
 #' <br/><br/>
 #' Clustering + Layers
@@ -39,8 +39,8 @@ names(quakes.df) %>%
                           label = ~as.character(mag),
                           popup = ~as.character(mag),
                           group = df,
-                          clusterOptions = markerClusterOptions(removeOutsideVisibleBounds = F),
-                          labelOptions = labelOptions(noHide = T,
+                          clusterOptions = markerClusterOptions(removeOutsideVisibleBounds = FALSE),
+                          labelOptions = labelOptions(noHide = TRUE,
                                                        direction = "auto"))
   })