Replace "function" with "command" in several user-facing doc (#15129)

crates/nu-cmd-lang/src/core_commands/return_.rs

@@ -10,7 +10,7 @@ impl Command for Return {
     }
 
     fn description(&self) -> &str {
-        "Return early from a function."
+        "Return early from a custom command."
     }
 
     fn signature(&self) -> nu_protocol::Signature {

crates/nu-std/std/assert/mod.nu

@@ -32,7 +32,6 @@ export def main [
     }
 }
 
-
 # Negative assertion
 #
 # If the condition is not false, it generates an error.

crates/nu-std/std/formats/mod.nu

@@ -1,40 +1,40 @@
 # formats.nu
 #
-# This file contains functions for formatting data in various ways.
+# This file contains helpers for formatting data in various ways.
 #
 # Usage:
-#   use std format *
+#   use std/format *
-#   use std format <function name>
+#   use std/format <command name>
 #
-# These functions help `open` the files with unsupported extensions such as ndjson.
+# These custom commands help `open` the files with unsupported extensions such as ndjson.
 #
 
-# Convert from [NDJSON](https://github.com/ndjson/ndjson-spec) to structured data.
+# Convert from NDJSON (https://github.com/ndjson/ndjson-spec) to structured data.
 export def "from ndjson" []: string -> any {
     from json --objects
 }
 
-# Convert from [JSONL](https://jsonlines.org/) to structured data.
+# Convert from JSONL (https://jsonlines.org/) to structured data.
 export def "from jsonl" []: string -> any {
     from json --objects
 }
 
-# Convert structured data to [NDJSON](https://github.com/ndjson/ndjson-spec).
+# Convert structured data to NDJSON (https://github.com/ndjson/ndjson-spec).
 export def "to ndjson" []: any -> string {
     each { to json --raw } | to text
 }
 
-# Convert structured data to [JSONL](https://jsonlines.org/).
+# Convert structured data to JSONL (https://jsonlines.org/).
 export def "to jsonl" []: any -> string {
     each { to json --raw } | to text
 }
 
-# Convert from NDNUON (newline-delimited NUON), to structured data
+# Convert from NDNUON (newline-delimited NUON) to structured data
 export def "from ndnuon" []: [string -> any] {
     lines | each { from nuon }
 }
 
-# Convert structured data to NDNUON, i.e. newline-delimited NUON
+# Convert structured data to newline-delimited NUON (NDNUON)
 export def "to ndnuon" []: [any -> string] {
     each { to nuon --raw | str replace --all "\n" '\n' } | to text
 }

crates/nu-std/std/iter/mod.nu

@@ -1,19 +1,16 @@
 # | Filter Extensions
 # 
-# This module implements extensions to the `filters` commands
+# This module implements extensions to the `filters` commands.
 #
-# They are prefixed with `iter` so as to avoid conflicts with 
+# They are prefixed with `iter` so as to avoid conflicts with the inbuilt filters.
-# the inbuilt filters
 
-# Returns the first element of the list that matches the
+# Returns the first element of the list that matches the closure predicate, `null` otherwise
-# closure predicate, `null` otherwise
 #
 # # Invariant
-# > The closure has to be a predicate (returning a bool value)
+#
-# > else `null` is returned
+# The closure must be a predicate (returning a bool value), otherwise `null` is returned.
-# > The closure also has to be valid for the types it receives
+# The closure also has to be valid for the types it receives.
-# > These will be flagged as errors later as closure annotations
+# These will be flagged as errors later as closure annotations are implemented.
-# > are implemented
 @example "Find an element starting with 'a'" {
     ["shell", "abc", "around", "nushell", "std"] | iter find {|e| $e starts-with "a" }
 } --result "abc"
@@ -24,11 +21,11 @@ export def find [
     filter {|e| try {do $fn $e} } | try { first }
 }
 
-# Returns the index of the first element that matches the predicate or
+# Returns the index of the first element that matches the predicate or -1 if none
-# -1 if none
 #
 # # Invariant
-# > The closure has to return a bool
+#
+# The closure must return a bool
 @example "Find the index of an element starting with 's'" {
     ["iter", "abc", "shell", "around", "nushell", "std"] | iter find-index {|x| $x starts-with 's'}
 } --result 2
@@ -43,8 +40,7 @@ export def find-index [
     | try { get index } catch { -1 }
 }
 
-# Returns a new list with the separator between adjacent
+# Returns a new list with the separator between adjacent items of the original list
-# items of the original list
 @example "Intersperse the list with `0`" {
     [1 2 3 4] | iter intersperse 0
 } --result [1 0 2 0 3 0 4]
@@ -60,11 +56,14 @@ export def intersperse [
     }
 }
 
-# Returns a list of intermediate steps performed by `reduce`
+# Returns a list of intermediate steps performed by `reduce` (`fold`).
-# (`fold`). It takes two arguments, an initial value to seed the
+#
-# initial state and a closure that takes two arguments, the first
+# It takes two arguments:
-# being the list element in the current iteration and the second
+# * an initial value to seed the initial state
-# the internal state.
+# * a closure that takes two arguments
+#   1. the list element in the current iteration
+#   2. the internal state
+#
 # The internal state is also provided as pipeline input.
 @example "Get a running sum of the input list" {
     [1 2 3] | iter scan 0 {|x, y| $x + $y}
@@ -84,9 +83,11 @@ export def scan [ # -> list<any>
     | if not $noinit { prepend $init } else { }
 }
 
-# Returns a list of values for which the supplied closure does not
+# Returns a list of values for which the supplied closure does not return `null` or an error.
-# return `null` or an error. It is equivalent to 
+#
-#     `$in | each $fn | filter $fn`
+# This is equivalent to 
+#
+#     $in | each $fn | filter $fn
 @example "Get the squares of elements that can be squared" {
     [2 5 "4" 7] | iter filter-map {|e| $e ** 2}
 } --result [4, 25, 49]

crates/nu-std/std/log/mod.nu

@@ -77,7 +77,6 @@ def log-types [] {
     )
 }
 
-
 def parse-string-level [
     level: string
 ] {
@@ -96,7 +95,6 @@ def parse-string-level [
     }
 }
 
-
 def parse-int-level [
     level: int,
     --short (-s)
@@ -320,6 +318,6 @@ def "nu-complete log-level" [] {
 
 # Change logging level
 export def --env set-level [level: int@"nu-complete log-level"] {
-    # Keep it as a string so it  can be passed to child processes
+    # Keep it as a string so it can be passed to child processes
     $env.NU_LOG_LEVEL = $level | into string
 }

crates/nu-std/std/mod.nu

@@ -1,4 +1,4 @@
-# std.nu, `used` to load all standard library components
+# std.nu, `use`d to load all standard library components
 
 # Top-level commands: ellie, repeat, null-device, and "path add"
 export use std/util *

crates/nu-std/std/prelude/mod.nu

@@ -1,6 +1,6 @@
 use std/dt [datetime-diff, pretty-print-duration]
 
-# Print a banner for nushell with information about the project
+# Print a banner for Nushell with information about the project
 export def banner [
     --short    # Only show startup time
 ] {

crates/nu-std/std/util/mod.nu

@@ -55,7 +55,7 @@ export def --env "path add" [
     }
 }
 
-# the cute and friendly mascot of Nushell :)
+# The cute and friendly mascot of Nushell :)
 export def ellie [] {
     let ellie = [
         "     __  ,",
@@ -67,7 +67,7 @@ export def ellie [] {
     $ellie | str join "\n" | $"(ansi green)($in)(ansi reset)"
 }
 
-# repeat anything a bunch of times, yielding a list of *n* times the input
+# Repeat anything a bunch of times, yielding a list of *n* times the input
 @example "repeat a string" {
     "foo" | std repeat 3 | str join
 } --result "foofoofoo"
@@ -101,7 +101,7 @@ export const null_device = if $nu.os-info.name == "windows" {
 	'/dev/null'
 }
 
-# return a null device file.
+# Return a null device file.
 @example "run a command and ignore it's stderr output" {
     cat xxx.txt e> (null-device)
 }

crates/nu-std/std/xml/mod.nu

@@ -1,5 +1,4 @@
-# Utility functions to read, change and create XML data in format supported
+# Custom commands to read, change and create XML data in format supported by the `to xml` and `from xml` commands
-# by `to xml` and `from xml` commands
 
 # Get all xml entries matching simple xpath-inspired query
 export def xaccess [
@@ -152,7 +151,7 @@ def xupdate-internal [ path: list updater: closure ] {
 
 }
 
-# Update xml data entries matching simple xpath-inspired query
+# Update XML data entries matching simple xpath-inspired query
 export def xupdate [
     path: list  # List of steps. Each step can be a
                 # 1. String with tag name. Finds all children with specified name. Equivalent to `child::A` in xpath
@@ -164,7 +163,7 @@ export def xupdate [
     {tag:? attributes:? content: [$in]} | xupdate-internal $path $updater | get content.0
 }
 
-# Get type of an xml entry
+# Get type of an XML entry
 #
 # Possible types are 'tag', 'text', 'pi' and 'comment'
 export def xtype [] {