From 1cbd7022f75bf860058a94cc13675f87dba3676f Mon Sep 17 00:00:00 2001
From: Michael Chirico <chiricom@google.com>
Date: Thu, 10 Aug 2023 22:27:15 +0000
Subject: [PATCH] meld documentation

---
 R/sort_linter.R    | 17 ++++++++++++++++-
 man/sort_linter.Rd | 18 +++++++++++++++++-
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/R/sort_linter.R b/R/sort_linter.R
index 87286a6c3..e8af983eb 100644
--- a/R/sort_linter.R
+++ b/R/sort_linter.R
@@ -1,9 +1,24 @@
-#' Require usage of `sort()` over `.[order(.)]`
+#' Check for common mistakes around sorting vectors
+#'
+#' This linter checks for some common mistakes when using [order()] or [sort()].
+#'
+#' First, it requires usage of `sort()` over `.[order(.)]`.
 #'
 #' [sort()] is the dedicated option to sort a list or vector. It is more legible
 #' and around twice as fast as `.[order(.)]`, with the gap in performance
 #' growing with the vector size.
 #'
+#' Second, it requires usage of [is.unsorted()] over equivalents using `sort()`.
+#'
+#' The base function `is.unsorted()` exists to test the sortedness of a vector.
+#'   Prefer it to inefficient and less-readable equivalents like
+#'   `x != sort(x)`. The same goes for checking `x == sort(x)` -- use
+#'   `!is.unsorted(x)` instead.
+#'
+#' Moreover, use of `x == sort(x)` can be risky because [sort()] drops missing
+#'   elements by default, meaning `==` might end up trying to compare vectors
+#'   of differing lengths.
+#'
 #' @examples
 #' # will produce lints
 #' lint(
diff --git a/man/sort_linter.Rd b/man/sort_linter.Rd
index d0cbbc7f6..d37bb543c 100644
--- a/man/sort_linter.Rd
+++ b/man/sort_linter.Rd
@@ -2,14 +2,30 @@
 % Please edit documentation in R/sort_linter.R
 \name{sort_linter}
 \alias{sort_linter}
-\title{Require usage of \code{sort()} over \code{.[order(.)]}}
+\title{Check for common mistakes around sorting vectors}
 \usage{
 sort_linter()
 }
 \description{
+This linter checks for some common mistakes when using \code{\link[=order]{order()}} or \code{\link[=sort]{sort()}}.
+}
+\details{
+First, it requires usage of \code{sort()} over \code{.[order(.)]}.
+
 \code{\link[=sort]{sort()}} is the dedicated option to sort a list or vector. It is more legible
 and around twice as fast as \code{.[order(.)]}, with the gap in performance
 growing with the vector size.
+
+Second, it requires usage of \code{\link[=is.unsorted]{is.unsorted()}} over equivalents using \code{sort()}.
+
+The base function \code{is.unsorted()} exists to test the sortedness of a vector.
+Prefer it to inefficient and less-readable equivalents like
+\code{x != sort(x)}. The same goes for checking \code{x == sort(x)} -- use
+\code{!is.unsorted(x)} instead.
+
+Moreover, use of \code{x == sort(x)} can be risky because \code{\link[=sort]{sort()}} drops missing
+elements by default, meaning \code{==} might end up trying to compare vectors
+of differing lengths.
 }
 \examples{
 # will produce lints