From 68e4911a8e20b0e2d80fbc0c49ca48b6bab740e9 Mon Sep 17 00:00:00 2001
From: Etienne Bacher <52219252+etiennebacher@users.noreply.github.com>
Date: Thu, 5 Oct 2023 10:56:06 +0000
Subject: [PATCH] Improve docs for `$suffix()`, `$prefix()`, `$reverse()`,
 `$lit()` (#411)

---
 R/expr__expr.R      | 66 ++++++++++++++++++++++++++--------------
 man/Expr.Rd         | 73 ---------------------------------------------
 man/Expr_lit.Rd     | 41 +++++++++++++++++++++++++
 man/Expr_prefix.Rd  | 31 +++++++++++++++++++
 man/Expr_reverse.Rd | 19 ++++++++++++
 man/Expr_suffix.Rd  | 31 +++++++++++++++++++
 6 files changed, 166 insertions(+), 95 deletions(-)
 delete mode 100644 man/Expr.Rd
 create mode 100644 man/Expr_lit.Rd
 create mode 100644 man/Expr_prefix.Rd
 create mode 100644 man/Expr_reverse.Rd
 create mode 100644 man/Expr_suffix.Rd

diff --git a/R/expr__expr.R b/R/expr__expr.R
index 69589a796..8e69e7348 100644
--- a/R/expr__expr.R
+++ b/R/expr__expr.R
@@ -900,24 +900,25 @@ Expr_apply = function(f, return_type = NULL, strict_return_type = TRUE, allow_fa
 }
 
 
-#' polars literal
-#' @keywords Expr
+#' Return an expression representing a literal value
+#'
+#' @param x An R Scalar, or R vector/list (via Series)
+#'
+#' @return Expr
 #'
-#' @param x an R Scalar, or R vector/list (via Series) into Expr
-#' @rdname Expr
-#' @return Expr, literal of that value
 #' @aliases lit
-#' @name Expr_lit
-#' @details pl$lit(NULL) translates into a typeless polars Null
+#' @details
+#' `pl$lit(NULL)` translates into a polars `null`.
+#'
 #' @examples
-#' # scalars to literal, explit `pl$lit(42)` implicit `+ 2`
+#' # scalars to literal, explicit `pl$lit(42)` implicit `+ 2`
 #' pl$col("some_column") / pl$lit(42) + 2
 #'
 #' # vector to literal explicitly via Series and back again
 #' # R vector to expression and back again
 #' pl$select(pl$lit(pl$Series(1:4)))$to_list()[[1L]]
 #'
-#' # r vecot to literal and back r vector
+#' # r vector to literal and back r vector
 #' pl$lit(1:4)$to_r()
 #'
 #' # r vector to literal to dataframe
@@ -928,44 +929,65 @@ Expr_apply = function(f, return_type = NULL, strict_return_type = TRUE, allow_fa
 #'
 #' # vectors to literal implicitly
 #' (pl$lit(2) + 1:4) / 4:1
+
 Expr_lit = function(x) {
-  .Call(wrap__Expr__lit, x) |> # use .call reduces eval from 22us to 15us, not a bottle-next anyways
+  # use .call reduces eval from 22us to 15us, not a bottle-next anyways
+  .Call(wrap__Expr__lit, x) |>
     unwrap("in $lit()")
 }
 
-#' polars suffix
+#' Add a suffix to a column name
 #' @keywords Expr
 #'
-#' @param suffix string suffix to be added to a name
-#' @rdname Expr
+#' @param suffix Suffix to be added to column name(s)
+#' @rdname Expr_suffix
 #' @return Expr
 #' @aliases suffix
-#' @name Expr_suffix
-#' @examples pl$col("some")$suffix("_column")
+#' @seealso
+#' [`$prefix()`][Expr_prefix] to add a prefix
+#' @examples
+#' dat = pl$DataFrame(mtcars)
+#'
+#' dat$select(
+#'   pl$col("mpg"),
+#'   pl$col("mpg")$suffix("_foo"),
+#'   pl$col("cyl", "drat")$suffix("_bar")
+#' )
+
 Expr_suffix = function(suffix) {
   .pr$Expr$suffix(self, suffix)
 }
 
-#' polars prefix
+#' Add a prefix to a column name
 #' @keywords Expr
 #'
-#' @param prefix string suffix to be added to a name
-#' @rdname Expr
+#' @param prefix Prefix to be added to column name(s)
+#' @rdname Expr_prefix
 #' @return Expr
 #' @aliases prefix
-#' @name Expr_prefix
-#' @examples pl$col("some")$suffix("_column")
+#' @seealso
+#' [`$suffix()`][Expr_suffix] to add a suffix
+#' @examples
+#' dat = pl$DataFrame(mtcars)
+#'
+#' dat$select(
+#'   pl$col("mpg"),
+#'   pl$col("mpg")$prefix("foo_"),
+#'   pl$col("cyl", "drat")$prefix("bar_")
+#' )
+
 Expr_prefix = function(prefix) {
   .pr$Expr$prefix(self, prefix)
 }
 
 #' polars reverse
 #' @keywords Expr
-#' @rdname Expr
 #' @return Expr
 #' @aliases reverse
 #' @name Expr_reverse
-#' @examples pl$DataFrame(list(a = 1:5))$select(pl$col("a")$reverse())
+#' @examples
+#' pl$DataFrame(list(a = 1:5))$select(pl$col("a")$reverse())
+
 Expr_reverse = function() {
   .pr$Expr$reverse(self)
 }
diff --git a/man/Expr.Rd b/man/Expr.Rd
deleted file mode 100644
index c9af240c9..000000000
--- a/man/Expr.Rd
+++ /dev/null
@@ -1,73 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/expr__expr.R
-\name{Expr_lit}
-\alias{Expr_lit}
-\alias{lit}
-\alias{Expr_suffix}
-\alias{suffix}
-\alias{Expr_prefix}
-\alias{prefix}
-\alias{Expr_reverse}
-\alias{reverse}
-\title{polars literal}
-\usage{
-Expr_lit(x)
-
-Expr_suffix(suffix)
-
-Expr_prefix(prefix)
-
-Expr_reverse()
-}
-\arguments{
-\item{x}{an R Scalar, or R vector/list (via Series) into Expr}
-
-\item{suffix}{string suffix to be added to a name}
-
-\item{prefix}{string suffix to be added to a name}
-}
-\value{
-Expr, literal of that value
-
-Expr
-
-Expr
-
-Expr
-}
-\description{
-polars literal
-
-polars suffix
-
-polars prefix
-
-polars reverse
-}
-\details{
-pl$lit(NULL) translates into a typeless polars Null
-}
-\examples{
-# scalars to literal, explit `pl$lit(42)` implicit `+ 2`
-pl$col("some_column") / pl$lit(42) + 2
-
-# vector to literal explicitly via Series and back again
-# R vector to expression and back again
-pl$select(pl$lit(pl$Series(1:4)))$to_list()[[1L]]
-
-# r vecot to literal and back r vector
-pl$lit(1:4)$to_r()
-
-# r vector to literal to dataframe
-pl$select(pl$lit(1:4))
-
-# r vector to literal to Series
-pl$lit(1:4)$lit_to_s()
-
-# vectors to literal implicitly
-(pl$lit(2) + 1:4) / 4:1
-pl$col("some")$suffix("_column")
-pl$col("some")$suffix("_column")
-pl$DataFrame(list(a = 1:5))$select(pl$col("a")$reverse())
-}
-\keyword{Expr}
diff --git a/man/Expr_lit.Rd b/man/Expr_lit.Rd
new file mode 100644
index 000000000..6aed52851
--- /dev/null
+++ b/man/Expr_lit.Rd
@@ -0,0 +1,41 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/expr__expr.R
+\name{Expr_lit}
+\alias{Expr_lit}
+\alias{lit}
+\title{Return an expression representing a literal value}
+\usage{
+Expr_lit(x)
+}
+\arguments{
+\item{x}{An R Scalar, or R vector/list (via Series)}
+}
+\value{
+Expr
+}
+\description{
+Return an expression representing a literal value
+}
+\details{
+\code{pl$lit(NULL)} translates into a polars \code{null}.
+}
+\examples{
+# scalars to literal, explicit `pl$lit(42)` implicit `+ 2`
+pl$col("some_column") / pl$lit(42) + 2
+
+# vector to literal explicitly via Series and back again
+# R vector to expression and back again
+pl$select(pl$lit(pl$Series(1:4)))$to_list()[[1L]]
+
+# r vector to literal and back r vector
+pl$lit(1:4)$to_r()
+
+# r vector to literal to dataframe
+pl$select(pl$lit(1:4))
+
+# r vector to literal to Series
+pl$lit(1:4)$lit_to_s()
+
+# vectors to literal implicitly
+(pl$lit(2) + 1:4) / 4:1
+}
diff --git a/man/Expr_prefix.Rd b/man/Expr_prefix.Rd
new file mode 100644
index 000000000..596d346ce
--- /dev/null
+++ b/man/Expr_prefix.Rd
@@ -0,0 +1,31 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/expr__expr.R
+\name{Expr_prefix}
+\alias{Expr_prefix}
+\alias{prefix}
+\title{Add a prefix to a column name}
+\usage{
+Expr_prefix(prefix)
+}
+\arguments{
+\item{prefix}{Prefix to be added to column name(s)}
+}
+\value{
+Expr
+}
+\description{
+Add a prefix to a column name
+}
+\examples{
+dat = pl$DataFrame(mtcars)
+
+dat$select(
+  pl$col("mpg"),
+  pl$col("mpg")$prefix("foo_"),
+  pl$col("cyl", "drat")$prefix("bar_")
+)
+}
+\seealso{
+\code{\link[=Expr_suffix]{$suffix()}} to add a suffix
+}
+\keyword{Expr}
diff --git a/man/Expr_reverse.Rd b/man/Expr_reverse.Rd
new file mode 100644
index 000000000..ba3335bc2
--- /dev/null
+++ b/man/Expr_reverse.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/expr__expr.R
+\name{Expr_reverse}
+\alias{Expr_reverse}
+\alias{reverse}
+\title{polars reverse}
+\usage{
+Expr_reverse()
+}
+\value{
+Expr
+}
+\description{
+polars reverse
+}
+\examples{
+pl$DataFrame(list(a = 1:5))$select(pl$col("a")$reverse())
+}
+\keyword{Expr}
diff --git a/man/Expr_suffix.Rd b/man/Expr_suffix.Rd
new file mode 100644
index 000000000..1c4e67d38
--- /dev/null
+++ b/man/Expr_suffix.Rd
@@ -0,0 +1,31 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/expr__expr.R
+\name{Expr_suffix}
+\alias{Expr_suffix}
+\alias{suffix}
+\title{Add a suffix to a column name}
+\usage{
+Expr_suffix(suffix)
+}
+\arguments{
+\item{suffix}{Suffix to be added to column name(s)}
+}
+\value{
+Expr
+}
+\description{
+Add a suffix to a column name
+}
+\examples{
+dat = pl$DataFrame(mtcars)
+
+dat$select(
+  pl$col("mpg"),
+  pl$col("mpg")$suffix("_foo"),
+  pl$col("cyl", "drat")$suffix("_bar")
+)
+}
+\seealso{
+\code{\link[=Expr_prefix]{$prefix()}} to add a prefix
+}
+\keyword{Expr}