add a bit of documentation

crates/nu-utils/standard_library/std.nu

@@ -385,14 +385,16 @@ export def "log debug" [message: string] {
     print --stderr $"(ansi default_dimmed)DBG|(now)|($message)(ansi reset)"
 }
 
+# print a command name as dimmed and italic
 def pretty-command [] {
     let command = $in
     return $"(ansi default_dimmed)(ansi default_italic)($command)(ansi reset)"
 }
 
+# give a hint error when the clip command is not available on the system
 def check-clipboard [
-    clipboard: string
-    --server: string
+    clipboard: string  # the clipboard command name
+    --server: string  # the graphical server running, for better error
 ] {
     if (which $clipboard | is-empty) {
         error make --unspanned {
@@ -404,9 +406,36 @@ def check-clipboard [
     }
 }
 
+# put the end of a pipe into the system clipboard.
+#
+# Dependencies:
+#   - xclip on linux x11
+#   - wl-copy on linux wayland
+#   - clip.exe on windows
+#
+# Examples:
+#     put a simple string to the clipboard, will be stripped to remove ANSI sequences
+#     >_ "my wonderfull string" | clip
+#     my wonderfull string
+#     saved to clipboard (stripped)
+#
+#     put a whole table to the clipboard
+#     >_ ls *.toml | clip
+#     ╭───┬─────────────────────┬──────┬────────┬───────────────╮
+#     │ # │        name         │ type │  size  │   modified    │
+#     ├───┼─────────────────────┼──────┼────────┼───────────────┤
+#     │ 0 │ Cargo.toml          │ file │ 5.0 KB │ 3 minutes ago │
+#     │ 1 │ Cross.toml          │ file │  363 B │ 2 weeks ago   │
+#     │ 2 │ rust-toolchain.toml │ file │ 1.1 KB │ 2 weeks ago   │
+#     ╰───┴─────────────────────┴──────┴────────┴───────────────╯
+#
+#     saved to clipboard
+#
+#     put huge structured data in the clipboard, but silently
+#     >_ open Cargo.toml --raw | from toml | clip --silent
 export def clip [
-    --silent: bool
-    --no-notify: bool
+    --silent: bool  # do not print the content of the clipboard to the standard output
+    --no-notify: bool  # do not throw a notification (only on linux)
 ] {
     let input = $in
     let input = if ($input | describe) == "string" {
@@ -414,7 +443,7 @@ export def clip [
     } else { $input }
 
     if not (which clip.exe | is-empty) {
-        chcp 65001
+        chcp 65001  # see https://discord.com/channels/601130461678272522/601130461678272524/1085535756237426778
         $input | clip.exe
     } else if ($env.WAYLAND_DISPLAY? | is-empty) {
         check-clipboard xclip --server "xorg"