Update command signature doc to modern syntax (#1167)

* Update command signature doc to modern syntax

While implementing a custom alias, I found myself unable to provide an explicit command signature as described in the documentation. A bit of crawling the main repo's commit history led to my discovery that the syntax as described in the documentation was indeed outdated. After a bit of experimentation I was able to discover the correct annotation syntax.
Ideally, in a slightly longer timescale than I am willing to deal with right now, this change shouldn't be needed; I believe the information on this page would serve better integrated with the rest of the documentation. It seems as though it would fit better there after the syntax change.

* Update signature doc with single type example

This should bring the syntax more in-line with the discussion in #1035.

* Update signature doc with clearer examples.

I've also removed the `cell-path` paragraph. It's probably fine(?) as again that should already be elsewhere.
Furthermore, I've decided that instead of omitting some types from `str distance` that instead it would be better to just select a command with one non-`<nothing>` pipeline signature. Surprisingly challenging! `histogram` seems like it should do the trick, though.

* Update signature doc primary example

amtoine suggested that `str stats` is used in the first example rather than `histogram`, as unlike `str stats`, `histogram` is not a default command.

book/command_signature.md

@@ -1,24 +1,22 @@
 # Command signature
 
-nu commands contain a signature section, take [`str distance`](/commands/docs/str_distance.md) as example, the signature is like this:
+nu commands can be given explicit signatures; take [`str stats`](/commands/docs/str_stats.md) as an example, the signature is like this:
 
 ```nu
-Signatures(Cell paths are supported):
-  <string> | str distance <string> -> <int>
+def "str stats" []: string -> record { }
 ```
 
-The first type name before `|` describes the type of input pipeline. The command name is followed by the required argument type(s) for the command. The output type is `int` and given after `->`.
-
-`(Cell paths are supported)` indicates that you can provide cell paths for `str distance` to apply an operation at the given cell path(s) in a nested structure or table, and replace the column or field with the result, like:  `ls | str distance 'nushell' 'name'`
-
-Here is another one example, [`str join`](/commands/docs/str_join.md):
+The type names between the `:` and the opening curly brace `{` describe the command's input/output pipeline types. The input type for a given pipeline, in this case `string`, is given before the `->`; and the output type `record` is given after `->`. There can be multiple input/output types. If there are multiple input/output types, they can be placed within brackets and separated with commas, as in [`str join`](/commands/docs/str_join.md):
 
 ```nu
-Signatures:
-  list<string> | str join <string?> -> <string>
+def "str join" [separator?: string]: [list -> string, string -> string] { }
 ```
 
-It says that [`str join`](/commands/docs/str_join.md) command expect input pipeline is a list of string, and take optional `string` type argument, finally the output type is `string`.
+It says that the [`str join`](/commands/docs/str_join.md) command takes an optional `string` type argument, and an input pipeline of either a `list` (implying `list<any>`) with output type of `string`, or a single `string`, again with output type of `string`.
 
 Some commands don't accept or require data through the input pipeline, thus the input type will be `<nothing>`.
-The same is true for the output type if the command returns `null` (e.g. [`rm`](/commands/docs/rm.md)).
+The same is true for the output type if the command returns `null` (e.g. [`rm`](/commands/docs/rm.md) or [`hide`](/commands/docs/hide.md)):
+
+```nu
+def hide [module: string, members?]: nothing -> nothing { }
+```