From 6cc3842dde4bca9021ca29fe323a0ea2b87699a5 Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sun, 17 May 2026 07:32:25 -0500 Subject: [PATCH 1/2] Formally include type in `@returns` similar to `@param`. --- .github/skills/document/SKILL.md | 16 ++++++++-------- inst/templates/skills/document/SKILL.md | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.github/skills/document/SKILL.md b/.github/skills/document/SKILL.md index 9914cdd..07a3321 100644 --- a/.github/skills/document/SKILL.md +++ b/.github/skills/document/SKILL.md @@ -66,19 +66,19 @@ When a parameter takes one of a fixed set of values, document them with a bullet ## Returns -Use `@returns` (not `@return`). Include a type when it's informative: +Use `@returns` (not `@return`). Include a type or types: ```r -#' @returns A summary tibble. +#' @returns (`tibble`) A summary tibble. #' @returns (`logical(1)`) `TRUE` if `x` is a valid record. -#' @returns Either a tibble or a list, depending on the input. -#' @returns `NULL` (invisibly). +#' @returns (`tibble` or `list`) Either a tibble or a list, depending on the input. +#' @returns (`NULL`, invisibly) Called for warning side effect. ``` **Structured returns with columns:** ```r -#' @returns A [tibble::tibble()] with columns: +#' @returns (`tibble`) A [tibble::tibble()] with columns: #' - `name`: Record name. #' - `value`: Numeric value. #' - `status`: Status (`"active"` or `"inactive"`). @@ -94,7 +94,7 @@ Use `@returns` (not `@return`). Include a type when it's informative: #' @param param_name (`TYPE`) Description. #' @inheritParams .shared-params #' -#' @returns Description of return value. +#' @returns (`TYPE`) Description of return value. #' @seealso [related_function()] #' @export #' @@ -132,7 +132,7 @@ Use `@rdname` to group related functions under one help page. This applies to: #' #' @param x (`any`) The object to format. #' @param ... Additional arguments passed to methods. -#' @returns A formatted character string. +#' @returns (`character(1)`) A formatted summary string. #' @keywords internal .format_summary <- function(x, ...) { UseMethod(".format_summary") @@ -152,7 +152,7 @@ Use `@rdname` to group related functions under one help page. This applies to: #' #' @param x (`TYPE`) Description. #' @param ... Additional arguments (ignored). -#' @returns Description. +#' @returns (`TYPE`) Description. #' @exportS3Method pkg::generic method.class <- function(x, ...) { ... } ``` diff --git a/inst/templates/skills/document/SKILL.md b/inst/templates/skills/document/SKILL.md index 9914cdd..07a3321 100644 --- a/inst/templates/skills/document/SKILL.md +++ b/inst/templates/skills/document/SKILL.md @@ -66,19 +66,19 @@ When a parameter takes one of a fixed set of values, document them with a bullet ## Returns -Use `@returns` (not `@return`). Include a type when it's informative: +Use `@returns` (not `@return`). Include a type or types: ```r -#' @returns A summary tibble. +#' @returns (`tibble`) A summary tibble. #' @returns (`logical(1)`) `TRUE` if `x` is a valid record. -#' @returns Either a tibble or a list, depending on the input. -#' @returns `NULL` (invisibly). +#' @returns (`tibble` or `list`) Either a tibble or a list, depending on the input. +#' @returns (`NULL`, invisibly) Called for warning side effect. ``` **Structured returns with columns:** ```r -#' @returns A [tibble::tibble()] with columns: +#' @returns (`tibble`) A [tibble::tibble()] with columns: #' - `name`: Record name. #' - `value`: Numeric value. #' - `status`: Status (`"active"` or `"inactive"`). @@ -94,7 +94,7 @@ Use `@returns` (not `@return`). Include a type when it's informative: #' @param param_name (`TYPE`) Description. #' @inheritParams .shared-params #' -#' @returns Description of return value. +#' @returns (`TYPE`) Description of return value. #' @seealso [related_function()] #' @export #' @@ -132,7 +132,7 @@ Use `@rdname` to group related functions under one help page. This applies to: #' #' @param x (`any`) The object to format. #' @param ... Additional arguments passed to methods. -#' @returns A formatted character string. +#' @returns (`character(1)`) A formatted summary string. #' @keywords internal .format_summary <- function(x, ...) { UseMethod(".format_summary") @@ -152,7 +152,7 @@ Use `@rdname` to group related functions under one help page. This applies to: #' #' @param x (`TYPE`) Description. #' @param ... Additional arguments (ignored). -#' @returns Description. +#' @returns (`TYPE`) Description. #' @exportS3Method pkg::generic method.class <- function(x, ...) { ... } ``` From 5b665bf67ba93ee37c82de0e73e7bfe197cacb0b Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sun, 17 May 2026 07:44:34 -0500 Subject: [PATCH 2/2] More type examples. --- .github/skills/document/SKILL.md | 5 +++++ inst/templates/skills/document/SKILL.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/.github/skills/document/SKILL.md b/.github/skills/document/SKILL.md index 07a3321..375e6b7 100644 --- a/.github/skills/document/SKILL.md +++ b/.github/skills/document/SKILL.md @@ -37,6 +37,8 @@ Function-specific `@param` definitions always appear *before* any `@inheritParam ### Type notation +These are non-exhaustive examples. Other classes (such as `httr2_response`) are possible + | Notation | Meaning | |----------|---------| | ``(`character`)`` | Character vector | @@ -49,9 +51,12 @@ Function-specific `@param` definitions always appear *before* any `@inheritParam | ``(`vector`)`` | A vector of unspecified type | | ``(`list`)`` | List | | ``(`data.frame`)`` | Data frame or tibble | +| ``(`tibble`)`` | Explicit tibble (when we KNOW the return is always a tibble) | +| ``(`NULL`)`` | NULL only | | ``(`function` or `NULL`)`` | A function or NULL | | ``(`my_class`)`` | A class-specific type (use the actual class name) | | ``(`any`)`` | Any type | +| ``(`NULL`, invisibly)`` | For returns, note `invisible()` returns with the type | ### Enumerated values diff --git a/inst/templates/skills/document/SKILL.md b/inst/templates/skills/document/SKILL.md index 07a3321..375e6b7 100644 --- a/inst/templates/skills/document/SKILL.md +++ b/inst/templates/skills/document/SKILL.md @@ -37,6 +37,8 @@ Function-specific `@param` definitions always appear *before* any `@inheritParam ### Type notation +These are non-exhaustive examples. Other classes (such as `httr2_response`) are possible + | Notation | Meaning | |----------|---------| | ``(`character`)`` | Character vector | @@ -49,9 +51,12 @@ Function-specific `@param` definitions always appear *before* any `@inheritParam | ``(`vector`)`` | A vector of unspecified type | | ``(`list`)`` | List | | ``(`data.frame`)`` | Data frame or tibble | +| ``(`tibble`)`` | Explicit tibble (when we KNOW the return is always a tibble) | +| ``(`NULL`)`` | NULL only | | ``(`function` or `NULL`)`` | A function or NULL | | ``(`my_class`)`` | A class-specific type (use the actual class name) | | ``(`any`)`` | Any type | +| ``(`NULL`, invisibly)`` | For returns, note `invisible()` returns with the type | ### Enumerated values