docs(std-rfc): use actual examples rather than doc comments (#15097)

# Description
Update examples with attributes.

# User-Facing Changes
`std-rfc` commands now have examples.

# Tests + Formatting
N/A

# After Submitting
N/A

crates/nu-std/std-rfc/clip/mod.nu

@@ -4,11 +4,9 @@
 # > Terminal multiplexers such as screen, tmux, zellij etc may interfere with this command
 
 # Copy input to system clipboard
-#
+@example "Copy a string to the clipboard" {
-# # Example
+  "Hello" | clip copy
-# ```nushell
+}
-# >_ "Hello" | clip copy
-# ```
 export def copy [
   --ansi (-a)                 # Copy ansi formatting
 ]: any -> nothing {
@@ -35,12 +33,9 @@ export def copy [
 }
 
 # Paste contents of system clipboard
-#
+@example "Paste a string from the clipboard" {
-# # Example
+  clip paste
-# ```nushell
+} --result "Hello"
-# >_ clip paste
-# "Hello"
-# ```
 export def paste []: [nothing -> string] {
 	try {
 		term query $'(ansi osc)52;c;?(ansi st)' -p $'(ansi osc)52;c;' -t (ansi st)
@@ -56,9 +51,17 @@ export def paste []: [nothing -> string] {
 }
 
 # Add a prefix to each line of the content to be copied
-#
+@example "Format output for Nushell doc" {
-# # Example: Format output for Nushell doc
+  [1 2 3] | clip prefix '# => '
-# ls | clip prefix '# => ' | clip copy
+} --result "# => ╭───┬───╮
+# => │ 0 │ 1 │
+# => │ 1 │ 2 │
+# => │ 2 │ 3 │
+# => ╰───┴───╯
+# => "
+@example "Format output for Nushell doc and copy it" {
+  ls | clip prefix '# => ' | clip copy
+}
 export def prefix [prefix: string]: any -> string {
   let input = $in | collect
   match ($input | describe -d | get type) {

crates/nu-std/std-rfc/conversions/mod.nu

@@ -1,10 +1,9 @@
 # Convert a Nushell value to a list
 # 
 # Primary useful for range-to-list, but other types are accepted as well.
-# 
+@example "Convert a range to a list" {
-# Example:
+    1..10 | into list
-#
+} --result [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
-# 1..10 | into list
 export def "into list" []: any -> list {
   let input = $in
   let type = ($input | describe --detailed | get type)
@@ -17,104 +16,53 @@ export def "into list" []: any -> list {
 }
 
 # Convert a list of columns into a table
-#
+@example "Construct a columns" {
-# Examples:
+    [
-#
+        ([1, 2, 3] | wrap a)
-# [
+        ([4, 5, 6] | wrap b)
-#  ([ 1 2 3 ] | wrap a)
+        ([7, 8, 9] | wrap c)
-#  ([ 4 5 6 ] | wrap b)
+    ] | columns-into-table 
-#  ([ 7 8 9 ] | wrap c)
+} --result [[a b c]; [1 4 7] [2 5 8] [3 6 9]]
-# ] | columns-into-table 
+@example "Can roundtrip with `table-into-columns`" {
-# => ╭───┬───┬───┬───╮
+  ls | table-into-columns | columns-into-table
-# => │ # │ a │ b │ c │
+}
-# => ├───┼───┼───┼───┤
-# => │ 0 │ 1 │ 4 │ 7 │
-# => │ 1 │ 2 │ 5 │ 8 │
-# => │ 2 │ 3 │ 6 │ 9 │
-# => ╰───┴───┴───┴───╯
-#
-# Can roundtrip with `table-into-columns`
-# 
-# ls | table-into-columns | columns-into-table
-# => ╭───┬────────────────────────┬──────┬────────┬────────────────╮
-# => │ # │          name          │ type │  size  │    modified    │
-# => ├───┼────────────────────────┼──────┼────────┼────────────────┤
-# => │ 0 │ into-list.nu           │ file │  378 B │ 40 minutes ago │
-# => │ 1 │ mod.nu                 │ file │   28 B │ 41 minutes ago │
-# => │ 2 │ name-values.nu         │ file │  394 B │ 34 minutes ago │
-# => │ 3 │ record-into-columns.nu │ file │ 1.3 kB │ 27 minutes ago │
-# => ╰───┴────────────────────────┴──────┴────────┴────────────────╯
 export def columns-into-table []: [list<table> -> table] {
     reduce {|it| merge $it}
 }
 
 # Convert a record, where each value is a list, into a list of columns.
-# { a: [ 1 2 3 ], b: [ 4 5 6 ] } | record-into-columns
+@example "Convert record of lists into list of columns" {
-# => ╭───┬───────────╮
+    { a: [1, 2, 3], b: [4, 5, 6] } | record-into-columns
-# => │ 0 │ ╭───┬───╮ │
+} --result [[[a]; [1], [2], [3]], [[b]; [4], [5], [6]]]
-# => │   │ │ # │ a │ │
+@example "This can be especially useful when combined with `columns-into-table`" {
-# => │   │ ├───┼───┤ │
+    { a: [1, 2, 3], b: [4, 5, 6] } | record-into-columns | columns-into-table
-# => │   │ │ 0 │ 1 │ │
+} --result [[a, b]; [1, 4], [2, 5], [3, 6]]
-# => │   │ │ 1 │ 2 │ │
-# => │   │ │ 2 │ 3 │ │
-# => │   │ ╰───┴───╯ │
-# => │ 1 │ ╭───┬───╮ │
-# => │   │ │ # │ b │ │
-# => │   │ ├───┼───┤ │
-# => │   │ │ 0 │ 4 │ │
-# => │   │ │ 1 │ 5 │ │
-# => │   │ │ 2 │ 6 │ │
-# => │   │ ╰───┴───╯ │
-# => ╰───┴───────────╯
-# =>
-# This can be especially useful when combined with `columns-into-table`, as in:
-#
-# { a: [ 1 2 3 ], b: [ 4 5 6 ] } | record-into-columns
-# | columns-into-table
-# => ╭───┬───┬───╮
-# => │ # │ a │ b │
-# => ├───┼───┼───┤
-# => │ 0 │ 1 │ 4 │
-# => │ 1 │ 2 │ 5 │
-# => │ 2 │ 3 │ 6 │
-# => ╰───┴───┴───╯
-# =>
 export def record-into-columns []: [record -> list] {
     items {|key, val| $val | wrap $key}
 }
 
 # Convert/split a table into a list of columns
-#
+@example "Return a list of 4 tables, one for each of the `ls` columns" {
-# Examples:
+    ls | table-into-columns 
-# ls | table-into-columns 
+}
-# => Returns a list of 4 tables, one for each of the `ls` columns
+@example "Can be roundtripped with `columns-into-table`" {
-#
+    ls | table-into-columns | columns-into-table
-# Can be roundtripped with `columns-into-table`
+} --result [
-#
+    [name, type, size, modified];
-# ls | table-into-columns | columns-into-table
+    ["into-list.nu", file, "378 B", 2025-02-09T20:52:38+03:00],
-# => ╭───┬────────────────────────┬──────┬────────┬────────────────╮
+    ["mod.nu", file, "28 B", 2025-02-09T20:51:38+03:00],
-# => │ # │          name          │ type │  size  │    modified    │
+    ["name-values.nu", file, "394 B", 2025-02-09T20:58:38+03:00],
-# => ├───┼────────────────────────┼──────┼────────┼────────────────┤
+    ["record-into-columns.nu", file, "1.3 kB", 2025-02-09T21:05:38+03:00]
-# => │ 0 │ into-list.nu           │ file │  378 B │ 40 minutes ago │
+]
-# => │ 1 │ mod.nu                 │ file │   28 B │ 41 minutes ago │
-# => │ 2 │ name-values.nu         │ file │  394 B │ 34 minutes ago │
-# => │ 3 │ record-into-columns.nu │ file │ 1.3 kB │ 27 minutes ago │
-# => ╰───┴────────────────────────┴──────┴────────┴────────────────╯
 export def table-into-columns []: [table -> list<table>] {
     let IN = $in
     $IN | columns | each {|col| $IN | select $col}
 }
 
 # Assign keynames to a list of values, effectively converting the list to a record.
-#
+@example "Name the items in a list" {
-# Example:
+    [1, 2, 3] | name-values a b c
-#
+} --result {a: 1, b: 2, c: 3}
-# [ 1 2 3 ] | name-values a b c
-# => ╭───┬───╮
-# => │ a │ 1 │
-# => │ b │ 2 │
-# => │ c │ 3 │
-# => ╰───┴───╯
 export def name-values [...names: string]: [list -> record] {
     let IN = $in
     0.. | zip $IN | into record | rename ...$names

crates/nu-std/std-rfc/kv/mod.nu

@@ -16,13 +16,15 @@
 #
 # If the key already exists, it is updated
 # to the new value provided.
-#
+@example "Store the list of files in the home directory" {
-# Usage:
+  ls ~ | kv set "home snapshot"
-# <input> | kv set <key> <value?>
+}
-#
+@example "Store a number" {
-# Example:
+  kv set foo 5
-# ls ~ | kv set "home snapshot"
+}
-# kv set foo 5
+@example "Update a number" {
+  kv set foo { $in + 1 }
+}
 export def "kv set" [
   key: string
   value_or_closure?: any
@@ -97,9 +99,9 @@ export def "kv set" [
 #
 # Counterpart of "kv set". Returns null
 # if the key is not found.
-# 
+@example "Retrieve a stored value" {
-# Usage:
+  kv get foo
-# kv get <key> | <pipeline>
+}
 export def "kv get" [
   key: string # Key of the kv-pair to retrieve
   --universal (-u)

crates/nu-std/std-rfc/path/mod.nu

@@ -5,25 +5,20 @@ def with-field [field: string, value: string] {
   | path join
 }
 
+alias "path with-extension" = with-extension
+
 # Replace extension of input file paths.
 #
 # Note that it doesn't change the file name locally.
-#
+@example "setting path ext to `rs`" {
-# # Example
+    "ab.txt" | path with-extension "rs"
-# - setting path ext to `rs`
+} --result ab.rs
-# ```nushell
+@example "leading dot can be included" {
-# > "ab.txt" | path with-extension "rs"
+    "ab.txt" | path with-extension ".rs"
-# ab.rs
+} --result ab.rs
-# > "ab.txt" | path with-extension ".rs"
+@example "setting a list of input path ext to `rs`" {
-# ab.rs
+    ["ab.txt", "cd.exe"] | path with-extension "rs"
-#
+} --result [ab.rs, cd.rs]
-# - setting a list of input path ext to `rs`
-# > ["ab.txt", "cd.exe"] | path with-extension "rs"
-# ╭───┬──────────╮
-# │ 0 │ ab.rs    │
-# │ 1 │ cd.rs    │
-# ╰───┴──────────╯
-# ```
 export def with-extension [ext: string] {
   let path = $in
   let ext_trim = if $ext starts-with "." {
@@ -34,38 +29,26 @@ export def with-extension [ext: string] {
   $path | with-field extension $ext_trim
 }
 
+alias "path with-stem" = with-stem
+
 # Replace stem of input file paths.
 #
 # Note that it doesn't change the file name locally.
-#
+@example "replace stem with 'share'" {
-# # Example
+    "/usr/bin" | path with-stem "share"
-# - replace stem with "share"
+} --result /usr/share
-# ```nushell
+@example "replace stem with 'nushell'" {
-# > "/usr/bin" | path with-stem "share"
+    ["/home/alice/", "/home/bob/secret.txt"] | path with-stem "nushell"
-# /usr/share
+} --result [/home/nushell, /home/bob/nushell.txt]
-#
-# - replace stem with "nushell"
-# > ["/home/alice/", "/home/bob/secret.txt"] | path with-stem "nushell"
-# ╭───┬───────────────────────╮
-# │ 0 │ /home/nushell         │
-# │ 1 │ /home/bob/nushell.txt │
-# ╰───┴───────────────────────╯
-# ```
 export def with-stem [stem: string] { with-field stem $stem }
 
+alias "path with-parent" = with-parent
+
 # Replace parent field of input file paths.
-#
+@example "replace parent path with `/usr/share`" {
-# # Example
+    "/etc/foobar" | path with-parent "/usr/share/"
-# - replace parent path with `/usr/share`
+} --result "/usr/share/foobar"
-# ```nushell
+@example "replace parent path with `/root/` for all filenames in list" {
-# > "/etc/foobar" | path with-parent "/usr/share/"
+    ["/home/rose/meow", "/home/fdncred/"] | path with-parent "/root/"
-# /usr/share/foobar
+} --result [/root/meow, /root/fdncred]
-#
-# - replace parent path with `/root/` for all filenames in list
-# > ["/home/rose/meow", "/home/fdncred/"] | path with-parent "/root/"
-# ╭───┬───────────────╮
-# │ 0 │ /root/meow    │
-# │ 1 │ /root/fdncred │
-# ╰───┴───────────────╯
-# ```
 export def with-parent [parent: string] { with-field parent $parent }

crates/nu-std/std-rfc/str/mod.nu

@@ -1,21 +1,19 @@
+alias "str dedent" = dedent
+
 # Removes common indent from a multi-line string based on the number of spaces on the last line.
-# 
+@example "Two leading spaces are removed from all lines" {
-# Example - Two leading spaces are removed from all lines:
+  "
-#
+  Heading
-# > let s = "
+    Indented Line
-#      Heading
+    Another Indented Line
-#        Indented Line
+
-#        Another Indented Line
+  Another Heading
-#
+  " | str dedent
-#      Another Heading
+} --result "Heading
-#      "
+  Indented Line
-# > $a | str dedent
+  Another Indented Line
-#
+
-# # => Heading
+Another Heading"
-# # =>   Indented Line
-# # =>   Another Indented Line
-# # => 
-# # => Another Heading
 export def dedent [
     --tabs (-t)
 ]: string -> string {
@@ -76,25 +74,22 @@ export def dedent [
     | str join (char line_sep)
 }
 
+alias "str unindent" = unindent
+
 # Remove common indent from a multi-line string based on the line with the smallest indent
-# 
+@example "Two leading spaces are removed from all lines" {
-# Example - Two leading spaces are removed from all lines:
+"
-#
+  Heading
-# > let s = "
+    Indented Line
-#      Heading
+    Another Indented Line
-#        Indented Line
+
-#        Another Indented Line
+  Another Heading
-#
+" | str unindent
-#      Another Heading
+} --result "Heading
-#   "
+  Indented Line
-# > $a | str dedent
+  Another Indented Line
-#
+
-# # => Heading
+Another Heading"
-# # =>   Indented Line
-# # =>   Another Indented Line
-# # =>
-# # => Another Heading
-#
 export def unindent [
     --tabs (-t)            # String uses tabs instead of spaces for indentation
 ]: string -> string {

crates/nu-std/std-rfc/tables/mod.nu

@@ -1,23 +1,15 @@
 # Run aggregate operations on output of `group-by --to-table`.
-#
+@example "group files by type and extension, and get stats about their sizes" {
-# # Example
+    ls | group-by type { get name | path parse | get extension } --to-table | aggregate size
-#
+}
-# - group files by type and extension, and get stats about their sizes
+@example "group data by multiple columns, and run custom aggregate operations" {
-# ```nushell
+    open movies.csv
-# >_ ls | group-by type { get name | path parse | get extension } --to-table | aggregate size
+    | group-by Lead_Studio Genre --to-table
-# ```
+    | aggregate Worldwide_Gross Profitability --ops {avg: {math avg}, std: {math stddev}}
-# 
+}
-# - group data by multiple columns, and run custom aggregate operations
+@example "run aggregate operations without grouping the input" {
-# ```nushell
+    open movies.csv | aggregate Year
-# >_ open movies.csv
+}
-#    | group-by Lead_Studio Genre --to-table
-#    | aggregate Worldwide_Gross Profitability --ops {avg: {math avg}, std: {math stddev}}
-# ```
-#
-# - run aggregate operations without grouping the input
-# ```nushell
-# >_ open movies.csv | aggregate Year
-# ```
 export def aggregate [
     --ops: record, # default = {min: {math min}, avg: {math avg}, max: {math max}, sum: {math sum}}  
     ...columns: cell-path, # columns to perform aggregations on
@@ -161,16 +153,12 @@ def row-indices [ ...slices ] {
 }
 
 # Selects one or more rows while keeping the original indices.
-#
+@example "Selects the first, fifth, and sixth rows from the table" {
-# Example - Selects the first, fifth, and sixth rows from the table:
+    ls / | select slices 0 4..5
-#
+}
-# ls / | select slices 0 4..5
+@example "Select the 4th row (difference to `select 3` is that the index (#) column shows the *original* (pre-select) position in the table)" {
-#
+    ls | select slices 3
-# Example - Select the 4th row.
+}
-#
-# Note that the difference between this and `select 3` is that the index (#) column shows the *original* (pre-select) position in the table.
-#
-# ls | select slices 3
 export def "select slices" [ ...slices ] {
   enumerate
   | flatten
@@ -178,10 +166,9 @@ export def "select slices" [ ...slices ] {
 }
 
 # Rejects one or more rows while keeping the original indices.
-#
+@example "Rejects the first, fifth, and sixth rows from the table" {
-# Example - Rejects the first, fifth, and sixth rows from the table:
+    ls / | reject slices 0 4..5
-#
+}
-# ls / | reject slices 0 4..5
 export def "reject slices" [ ...slices ] {
   enumerate
   | flatten
@@ -190,17 +177,14 @@ export def "reject slices" [ ...slices ] {
 }
 
 # Select one or more columns by their indices
-#
+@example "Select column [0, 10, 11, 12]" {
-# Example:
+    ls -l | select column-slices 0 10..12 | first 3
-# 
+} --result [
-# ls -l | select column-slices 0 10..12 | first 3
+    [name, created, accessed, modified];
-# # => ╭───┬────────────────────┬──────────────┬─────────────┬──────────────╮
+    ["CITATION.cff", 2024-11-09T21:58:12+03:00, 2025-02-09T17:58:12+03:00, 2024-11-09T21:58:12+03:00],
-# # => │ # │        name        │   created    │  accessed   │   modified   │
+    ["CODE_OF_CONDUCT.md", 2024-07-09T21:58:12+03:00, 2025-02-09T17:58:12+03:00, 2024-07-09T21:58:12+03:00],
-# # => ├───┼────────────────────┼──────────────┼─────────────┼──────────────┤
+    ["CONTRIBUTING.md", 2024-11-09T21:58:12+03:00, 2025-02-09T17:58:12+03:00, 2024-11-09T21:58:12+03:00]
-# # => │ 0 │ CITATION.cff       │ 3 months ago │ 4 hours ago │ 3 months ago │
+]
-# # => │ 1 │ CODE_OF_CONDUCT.md │ 7 months ago │ 4 hours ago │ 7 months ago │
-# # => │ 2 │ CONTRIBUTING.md    │ 3 months ago │ 4 hours ago │ 3 months ago │
-# # => ╰───┴────────────────────┴──────────────┴─────────────┴──────────────╯
 export def "select column-slices" [
     ...slices
 ] {
@@ -209,10 +193,9 @@ export def "select column-slices" [
 }
 
 # Reject one or more columns by their indices
-#
+@example "Reject columns [0, 4, 5]" {
-# Example:
+    ls | reject column-slices 0 4 5 | first 3
-#
+}
-# ls | reject column-slices 0 4 5 | first 3
 export def "reject column-slices" [
     ...slices
 ] {