docs: add missing @return tags to exported functions

R/char.R

@@ -2,6 +2,8 @@
 #'
 #' These functions are reexported as [tibble::char()] and [tibble::set_char_opts()].
 #'
+#' @return A `pillar_char` vector for `char()`, or `x` with pillar attributes
+#'   set for `set_char_opts()`.
 #' @keywords internal
 #' @export
 char <- function(x, ..., min_chars = NULL,

R/ctl_new_pillar.R

@@ -31,6 +31,8 @@
 #' @param width The available width, can be a vector for multiple tiers.
 #' @param title The title, derived from the name of the column in the data.
 #'
+#' @return A pillar object, or `NULL` if none of the data fits the available width.
+#'
 #' @seealso
 #' See [ctl_new_pillar_list()] for creating pillar objects for compound columns:
 #' packed data frames, matrices, or arrays.

R/ctl_new_pillar_list.R

@@ -41,6 +41,7 @@
 #' @param first_pillar Can be passed to this method if the first pillar
 #'   for a compound pillar (or the pillar itself for a simple pillar)
 #'   has been constructed already.
+#' @return A list of pillar objects.
 #' @export
 #' @examplesIf rlang::is_installed(c("palmerpenguins", "tibble")) && requireNamespace("tibble")
 #' # Simple column

R/ctl_pillar.R

@@ -23,6 +23,8 @@
 #'   used "as is", no quoting will be applied.
 #' @param width Default width, optional.
 #' @param ... Passed on to [pillar_shaft()].
+#' @return A pillar object, or `NULL` if the width is insufficient
+#'   to display the data.
 #' @export
 #' @examples
 #' x <- 123456789 * (10^c(-1, -3, -5, NA, -8, -10))
@@ -129,6 +131,7 @@ pillar_from_shaft <- function(title, type, data, width) {
 #' @param class Name of subclass.
 #' @param extra Deprecated.
 #'
+#' @return A pillar object with the given components.
 #' @export
 #' @examples
 #' lines <- function(char = "-") {

R/ctl_pillar_component.R

@@ -23,6 +23,7 @@
 #'   (for `pillar_component()`).
 #' @param width,min_width Width and minimum width for the new component.
 #'   If `min_width` is `NULL`, it is assumed to match `width`.
+#' @return A `"pillar_component"` object.
 #' @export
 #' @examples
 #' new_pillar_component(list(letters[1:3]), width = 1)

R/dim.R

@@ -5,6 +5,8 @@
 #'
 #' @param x The object to format the dimensions for
 #'
+#' @return A string describing the dimensions, e.g. `"10"` for a vector
+#'   or `"32 x 11"` for a data frame.
 #' @export
 #' @examples
 #' dim_desc(1:10)

R/extent.R

@@ -4,6 +4,7 @@
 #' vector.
 #'
 #' @param x A character vector.
+#' @return An integer vector of display widths, one per element of `x`.
 #' @export
 #' @importFrom cli ansi_strip
 #' @importFrom cli utf8_nchar
@@ -24,6 +25,8 @@ get_extent <- function(x) {
 #' @description
 #' `get_max_extent()` calculates the maximum display width of all strings in a
 #' character vector, zero for empty vectors.
+#'
+#' @return A single integer value representing the maximum display width.
 #' @export
 #' @rdname get_extent
 #' @examples
@@ -43,6 +46,7 @@ get_max_extent <- function(x) {
 #' @param align How should strings be aligned? If `align = left` then padding
 #'   appears on the `right`, and vice versa.
 #' @param space What character should be used for the padding?
+#' @return A character vector of aligned and padded strings.
 #' @export
 #' @examples
 #' align(c("abc", "de"), align = "left")

R/ggplot2.R

@@ -8,6 +8,7 @@
 #' @inheritDotParams ggplot2::continuous_scale -scale_name
 #' @param guide,position Passed on to [ggplot2::continuous_scale()]
 #' @param rescaler,super Must remain `NULL`.
+#' @return A ggplot2 scale object.
 #'
 #' @keywords internal
 #' @export

R/num.R

@@ -2,6 +2,8 @@
 #'
 #' These functions are reexported as [tibble::num()] and [tibble::set_num_opts()].
 #'
+#' @return A `pillar_num` vector for `num()`, or `x` with pillar attributes
+#'   set for `set_num_opts()`.
 #' @keywords internal
 #' @export
 num <- function(x, ...,

R/ornament.R

@@ -7,12 +7,13 @@
 #' `pillar_shaft.numeric()` and `format.pillar_shaft_decimal()` for an example.
 #'
 #' @param x A character vector with formatting,
-#'   can use ANYI styles e.g provided by the \pkg{cli} package.
+#'   can use ANSI styles e.g provided by the \pkg{cli} package.
 #'
 #' @param width An optional width of the resulting pillar, computed from `x` if
 #'   missing
 #' @param align Alignment, one of `"left"` or `"right"`
 #'
+#' @return A `pillar_ornament` object.
 #' @export
 #' @examples
 #' new_ornament(c("abc", "de"), align = "right")

R/shaft-.R

@@ -30,6 +30,7 @@
 #'   [type_sum()].
 #' @param class The name of the subclass.
 #' @param subclass Deprecated, pass the `class` argument instead.
+#' @return A pillar shaft object of class `c(class, "pillar_shaft")`.
 #' @name new_pillar_shaft
 #' @export
 new_pillar_shaft <- function(x, ..., width = NULL, min_width = width,
@@ -62,6 +63,7 @@ new_pillar_shaft <- function(x, ..., width = NULL, min_width = width,
 #'
 #' @param x A vector to format
 #' @inheritParams rlang::args_dots_used
+#' @return A pillar shaft object.
 #' @export
 #' @examples
 #' pillar_shaft(1:3)

R/styles.R

@@ -17,6 +17,7 @@ keep_empty <- function(fun) {
 #' `style_subtle()` is affected by the `subtle` [option][pillar_options].
 #'
 #' @param x The character vector to style.
+#' @return A styled character vector.
 #' @export
 #' @seealso [pillar_options] for a list of options
 #' @examples

R/tbl-format-setup.R

@@ -221,6 +221,8 @@ tbl_format_setup.tbl <- function(
 #'
 #' @param x A tbl object.
 #' @inheritParams rlang::args_dots_empty
+#' @return A single integer, or `NA` if the number of rows is unknown
+#'   (e.g., for lazy tables).
 #' @export
 tbl_nrow <- function(x, ...) {
   check_dots_empty0(...)

R/title.R

@@ -6,6 +6,7 @@ style_title <- style_bold
 #'
 #' @param x A character vector of column titles.
 #' @inheritParams rlang::args_dots_empty
+#' @return A `"pillar_title"` object.
 #' @export
 #' @examples
 #' format(new_pillar_title(names(trees)))

R/type-sum.R

@@ -12,6 +12,7 @@
 #' @param x an object to summarise. Generally only methods of atomic vectors
 #'   and variants have been implemented.
 #'
+#' @return A string with four or less characters summarising the type of `x`.
 #' @export
 type_sum <- function(x) {
   UseMethod("type_sum")
@@ -72,6 +73,9 @@ vec_ptype_abbr.pillar_empty_col <- function(x, ...) {
 #' An attribute named `"short"` in the return value will be picked up by
 #' the [pillar_shaft()] method for lists, and used if space is limited.
 #'
+#' @return A string summarising the object, including its type and size
+#'   for vectors. An attribute named `"short"` may contain a shorter version.
+#'
 #' @examples
 #' obj_sum(1:10)
 #' obj_sum(matrix(1:10))
@@ -114,6 +118,9 @@ obj_sum.AsIs <- function(x) {
 #' it can be an empty string `""` to omit size information,
 #' this is what the default method does for scalars.
 #'
+#' @return A string describing the size, e.g. `"[10]"` or `"[32 x 11]"`.
+#'   Returns `""` for scalars.
+#'
 #' @keywords internal
 #' @examples
 #'

R/type.R

@@ -13,6 +13,7 @@ style_type <- function(x) {
 #'
 #' @param x A vector for which the type is to be retrieved.
 #' @inheritParams rlang::args_dots_empty
+#' @return A `"pillar_type"` object.
 #' @export
 #' @examples
 #' format(new_pillar_type("a"))
@@ -72,6 +73,7 @@ format_full_pillar_type <- function(x) {
 #' @param width The desired total width. If the returned string still is
 #'   wider, it will be trimmed. Can be `NULL`.
 #' @inheritParams rlang::args_dots_used
+#' @return A styled character string summarising the type.
 #'
 #' @export
 #' @examples