Formally include type in @returns similar to @param

.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
 
@@ -66,19 +71,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 +99,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 +137,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 +157,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, ...) { ... }
 ```

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
 
@@ -66,19 +71,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 +99,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 +137,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 +157,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, ...) { ... }
 ```