docs: several cleanup changes (#1194)

R/Field.R

@@ -18,12 +18,10 @@
 #'
 #' `$name = "new_name"` sets the name of the Field.
 #'
-#' @aliases RField_class RPolarsRField
-#'
 #' @param name Field name
 #' @param datatype [DataType][pl_dtypes]
 #'
-#' @return An [RPolarsRField] object containing its name and its
+#' @return An object of class `"RPolarsRField"` containing its name and its
 #' [data type][pl_dtypes].
 #'
 # Named like this because R cannot have two man pages called "pl_Field" and

R/datatype.R

@@ -85,12 +85,15 @@ print.RPolarsDataType = function(x, ...) {
 "!=.RPolarsDataType" = function(e1, e2) e1$ne(e2)
 
 
-#' check if x is a valid RPolarsDataType
-#' @name same_outer_datatype
-#' @param lhs an RPolarsDataType
-#' @param rhs an RPolarsDataType
+#' Check if two DataTypes share the same outer DataType
+#'
+#'
+#' @param lhs RPolarsDataType
+#' @param rhs RPolarsDataType
+#'
 #' @noRd
-#' @return bool TRUE if outer datatype is the same.
+#' @name same_outer_datatype
+#' @return A logical.
 #' @examples
 #' # TRUE
 #' pl$same_outer_dt(pl$Datetime("us"), pl$Datetime("ms"))
@@ -103,51 +106,42 @@ pl_same_outer_dt = function(lhs, rhs) {
 }
 
 
-#' DataType_new (simple DataType's)
-#' @noRd
-#' @description Create a new flag like DataType
-#' @param str name of DataType to create
+#' Create a new DataType (internal)
+#'
+#' @param str Name of DataType to create
+#'
 #' @details
 #' This function is mainly used in `zzz.R` `.onLoad` to instantiate singletons of all
 #' flag-like DataType.
 #'
-#' Non-flag like DataType called composite DataTypes also carries extra information
-#' e.g. Datetime a timeunit and a TimeZone, or List which recursively carries another DataType
-#' inside. Composite DataTypes use DataType constructors.
-#'
-#' Any DataType can be found in pl$dtypes
-#'
+#' @noRd
 #' @return DataType
 #' @examples
 #' .pr$env$DataType_new("Int64")
 DataType_new = function(str) {
   .pr$DataType$new(str)
 }
 
-#' DataType_constructors (composite DataType's)
-#' @description List of all composite DataType constructors
-#' @noRd
+#' DataType_constructors (internal)
+#'
+#' List of all composite DataType constructors
+#'
 #' @details
 #' This list is mainly used in `zzz.R` `.onLoad` to instantiate singletons of all
 #' flag-like DataTypes.
 #'
-#' Non-flag like DataType called composite DataTypes also carries extra information
-#' e.g. Datetime a timeunit and a TimeZone, or List which recursively carries another DataType
-#' inside. Composite DataTypes use DataType constructors.
-#'
-#' Any DataType can be found in pl$dtypes
-#'
 #' @return DataType
+#' @noRd
 #' @examples
 #' # constructors are finally available via pl$... or pl$dtypes$...
 #' pl$List(pl$List(pl$Int64))
 DataType_constructors = function() {
   list(
     Array = DataType_Array,
     Categorical = DataType_Categorical,
-    Enum = DataType_Enum,
     Datetime = DataType_Datetime,
     Duration = DataType_Duration,
+    Enum = DataType_Enum,
     List = DataType_List,
     Struct = DataType_Struct
   )
@@ -182,9 +176,10 @@ DataType_Datetime = function(time_unit = "us", time_zone = NULL) {
       time_zone
     ) |>
       Err_plain() |>
-      unwrap("in $Datetime():")
+      unwrap("in pl$Datetime():")
   }
-  unwrap(.pr$DataType$new_datetime(time_unit, time_zone))
+  .pr$DataType$new_datetime(time_unit, time_zone) |>
+    unwrap("in pl$Datetime():")
 }
 
 #' Data type representing a time duration
@@ -287,6 +282,7 @@ DataType_Struct = function(...) {
 #' @param datatype An inner DataType. The default is `"Unknown"` and is only a
 #' placeholder for when inner DataType does not matter, e.g. as used in example.
 #' @param width The length of the arrays.
+#'
 #' @return An array DataType with an inner DataType
 #' @examples
 #' # basic Array
@@ -308,10 +304,10 @@ DataType_Array = function(datatype = "unknown", width) {
 }
 
 #' Create List DataType
-#' @keywords pl
-#' @param datatype an inner DataType, default is "Unknown" (placeholder for when inner DataType
-#' does not matter, e.g. as used in example)
-#' @return a list DataType with an inner DataType
+#'
+#' @param datatype The inner DataType.
+#'
+#' @return A list DataType with an inner DataType
 #' @examples
 #' # some nested List
 #' pl$List(pl$List(pl$Boolean))

R/expr__array.R

@@ -1,7 +1,6 @@
 #' Sum all elements in an array
 #'
 #' @return Expr
-#' @aliases arr_sum
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(1, 2), c(3, 4), c(NA_real_, 6)),
@@ -14,7 +13,6 @@ ExprArr_sum = function() .pr$Expr$arr_sum(self)
 #'
 #' @return Expr
 #' @inherit ExprStr_to_titlecase details
-#' @aliases arr_max
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(1, 2), c(3, 4), c(NA_real_, NA_real_)),
@@ -29,7 +27,6 @@ ExprArr_max = function() {
 #'
 #' @inherit ExprStr_to_titlecase details
 #' @return Expr
-#' @aliases arr_min
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(1, 2), c(3, 4), c(NA_real_, NA_real_)),
@@ -43,7 +40,6 @@ ExprArr_min = function() {
 #' Find the median in an array
 #'
 #' @return Expr
-#' @aliases arr_median
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(2, 1, 4), c(8.4, 3.2, 1)),
@@ -58,7 +54,6 @@ ExprArr_median = function() {
 #'
 #' @inheritParams DataFrame_std
 #' @return Expr
-#' @aliases arr_std
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(2, 1, 4), c(8.4, 3.2, 1)),
@@ -73,7 +68,6 @@ ExprArr_std = function(ddof = 1) {
 #'
 #' @inheritParams DataFrame_var
 #' @return Expr
-#' @aliases arr_var
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(2, 1, 4), c(8.4, 3.2, 1)),
@@ -87,7 +81,6 @@ ExprArr_var = function(ddof = 1) {
 #' Sort values in an array
 #'
 #' @inheritParams Expr_sort
-#' @aliases arr_sort
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(2, 1), c(3, 4), c(NA_real_, 6)),
@@ -99,7 +92,6 @@ ExprArr_sort = function(descending = FALSE, nulls_last = FALSE) .pr$Expr$arr_sor
 #' Reverse values in an array
 #'
 #' @return Expr
-#' @aliases arr_reverse
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(1, 2), c(3, 4), c(NA_real_, 6)),
@@ -112,7 +104,6 @@ ExprArr_reverse = function() .pr$Expr$arr_reverse(self)
 #'
 #' @inheritParams Expr_unique
 #' @return Expr
-#' @aliases arr_unique
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c(1, 1, 2), c(4, 4, 4), c(NA_real_, 6, 7)),
@@ -154,7 +145,6 @@ ExprArr_get = function(index, ..., null_on_oob = TRUE) {
 #' as columns.
 #'
 #' @return Expr
-#' @aliases arr_contains
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(0:2, 4:6, c(NA_integer_, NA_integer_, NA_integer_)),
@@ -177,7 +167,6 @@ ExprArr_contains = function(item) .pr$Expr$arr_contains(self, item)
 #' @inheritParams pl_concat_str
 #'
 #' @return Expr
-#' @aliases arr_join
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(c("a", "b", "c"), c("x", "y", "z"), c("e", NA, NA)),
@@ -197,7 +186,6 @@ ExprArr_join = function(separator, ignore_nulls = FALSE) {
 #' Get the index of the minimal value in an array
 #'
 #' @return Expr
-#' @aliases arr_arg_min
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(1:2, 2:1),
@@ -211,7 +199,6 @@ ExprArr_arg_min = function() .pr$Expr$arr_arg_min(self)
 #' Get the index of the maximal value in an array
 #'
 #' @return Expr
-#' @aliases arr_arg_max
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(1:2, 2:1),
@@ -249,7 +236,6 @@ ExprArr_any = function() .pr$Expr$arr_any(self)
 #' @inheritParams ExprList_shift
 #'
 #' @return Expr
-#' @aliases arr_shift
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(1:3, c(2L, NA_integer_, 5L)),
@@ -286,7 +272,6 @@ ExprArr_to_list = function() .pr$Expr$arr_to_list(self)
 #' @inheritParams ExprList_to_struct
 #'
 #' @return Expr
-#' @aliases arr_to_struct
 #' @examples
 #' df = pl$DataFrame(
 #'   values = list(1:3, c(2L, NA_integer_, 5L)),

R/expr__categorical.R

@@ -1,13 +1,13 @@
 #' Set Ordering
 #'
-#' @aliases expr_cat_set_ordering
-#' @description Determine how this categorical series should be sorted.
-#' @keywords ExprCat
+#' Determine how this categorical series should be sorted.
+#'
 #' @param ordering string either 'physical' or 'lexical'
-#' - 'physical' -> Use the physical representation of the categories to
-#'                 determine the order (default).
-#' - 'lexical' -> Use the string values to determine the ordering.
-#' @return bool: TRUE if equal
+#' - `"physical"`: use the physical representation of the categories to
+#'   determine the order (default).
+#' - `"lexical"`: use the string values to determine the order.
+#'
+#' @return An Expr of datatype Categorical
 #' @examples
 #' df = pl$DataFrame(
 #'   cats = factor(c("z", "z", "k", "a", "b")),
@@ -24,13 +24,13 @@
 #'   pl$col("cats")$cat$set_ordering("physical")
 #' )$sort("cats", "vals")
 ExprCat_set_ordering = function(ordering) {
-  .pr$Expr$cat_set_ordering(self, ordering) |> unwrap("in $cat$set_ordering:")
+  .pr$Expr$cat_set_ordering(self, ordering) |>
+    unwrap("in $cat$set_ordering:")
 }
 
 
 #' Get the categories stored in this data type
 #'
-#' @keywords ExprCat
 #' @return A polars DataFrame with the categories for each categorical Series.
 #' @examples
 #' df = pl$DataFrame(