Documentation improvements (#633)

* Fix `is_online()` exports
* Improve `req_url()` docs

R/is-online.R

@@ -5,6 +5,7 @@
 #' exported from httr2 for convenience.
 #'
 #' @export
+#' @examples
 #' is_online()
 is_online <- function() {
   curl::has_internet()

R/req-url.R

@@ -1,16 +1,19 @@
 #' Modify request URL
 #'
 #' @description
-#' * `req_url()` replaces the entire url
-#' * `req_url_query()` modifies the components of the query
-#' * `req_url_path()` modifies the path
-#' * `req_url_path_append()` adds to the path
-#'
-#' Alternatively, to modify only a URL without creating a request,
-#' you can instead use [url_modify()] and friends.
+#' * `req_url()` replaces the entire URL.
+#' * `req_url_relative()` navigates to a relative URL.
+#' * `req_url_query()` modifies individual query components.
+#' * `req_url_path()` modifies just the path.
+#' * `req_url_path_append()` adds to the path.
 #'
+#' @seealso
+#' * To modify a URL without creating a request, see [url_modify()] and
+#'   friends.
+#' * To use a template like `GET /user/{user}`, see [req_template()].
 #' @inheritParams req_perform
-#' @param url New URL; completely replaces existing.
+#' @param url A new URL; either an absolute URL for `req_url()` or a
+#'   relative URL for `req_url_relative()`.
 #' @param ... For `req_url_query()`: <[`dynamic-dots`][rlang::dyn-dots]>
 #'   Name-value pairs that define query parameters. Each value must be either
 #'   an atomic vector or `NULL` (which removes the corresponding parameters).
@@ -21,7 +24,14 @@
 #' @returns A modified HTTP [request].
 #' @export
 #' @examples
+#' # Change complete url
 #' req <- request("http://example.com")
+#' req |> req_url("http://google.com")
+#'
+#' # Use a relative url
+#' req <- request("http://example.com/a/b/c")
+#' req |> req_url_relative("..")
+#' req |> req_url_relative("/d/e/f")
 #'
 #' # Change url components
 #' req |>
@@ -30,14 +40,11 @@
 #'   req_url_path_append("search.html") |>
 #'   req_url_query(q = "the cool ice")
 #'
-#' # Change complete url
-#' req |>
-#'   req_url("http://google.com")
-#'
-#' # Use a relative url
-#' req <- request("http://example.com/a/b/c")
-#' req |> req_url_relative("..")
-#' req |> req_url_relative("/d/e/f")
+#' # Modify individual query parameters
+#' req <- request("http://example.com?a=1&b=2")
+#' req |> req_url_query(a = 10)
+#' req |> req_url_query(a = NULL)
+#' req |> req_url_query(c = 3)
 #'
 #' # Use .multi to control what happens with vector parameters:
 #' req |> req_url_query(id = 100:105, .multi = "comma")