Add a note about the column name restriction of join_by()

NEWS.md

@@ -14,6 +14,10 @@
     joins and rolling joins. These allow you to join on conditions other than
     equality. For example, to find every commercial that aired before a
     particular sale was made, you'd use `join_by(sale_date >= commercial_date)`.
+    Note that you cannot use arbitrary expressions on each side of the join
+    condition, like `join_by(sale_date - 40 >= commercial_date)`. Instead,
+    create a new column containing `sale_date - 40` and refer to that by name
+    instead.
 
   * `keep` now defaults to `NULL` rather than `FALSE`. `NULL` implies
     `keep = FALSE` for equi-join conditions, but `keep = TRUE` for non-equi

R/join-by.R

@@ -30,6 +30,13 @@
 #' the matches in `y`. To construct a rolling join, wrap a non-equi join
 #' condition in `max()` or `min()`, such as `max(x > y)`.
 #'
+#' @details
+#' Note that `join_by()` does not support arbitrary expressions on each side of
+#' the join condition. For example, `join_by(sales_date - 40 >=
+#' commercial_date)` is not allowed. To perform a join like this, pre-compute
+#' `sales_date - 40` and store it in a separate column, like `sales_date_lower`,
+#' and refer to that column by name in `join_by()`.
+#'
 #' @param ... Expressions specifying the join. Each expression should consist
 #'   of:
 #'   - A join condition, one of: `==`, `>`, `>=`, `<`, or `<=`.