Documentation for 'def' keyword signature should include optional syntax for the return type of the custom command

[edhowland]

Describe the bug

Custom commands defined using the 'def' keyword allow, in addition to specifying
the optional parameter types, also allow for specifying an optional return
type. E.g.

# returns the square of the parameter
def square [x: int] -> int {
  $x * $x
}

The '-> ' is not mentioned in any of the documentation for either
the 'def' keyword or the Nushell book chapter on Custom Commands:

The def keyword

https://www.nushell.sh/commands/docs/def.html

Note: The same text as in the command reference for the 'def' keyword is output
when you type:

help def

and should also include the optional '-> part of the signature.

The Custom Command chapter

https://www.nushell.sh/book/custom_commands.html

In the command reference or the help text there should be:

1. Part of the signature between the parameters and the body should be the return type.
2. Examples of using the 'def' keyword should include an example with the '->

• Perhaps like the square example above.

In the chapter on "Custom Commands",
there should be a Heading 2 section called something like

Specifying the return type of your command

Custom commands can optionally specify their return type which helps the Nushell
compiler to check your usage when calling your custom command especially in an expression.

Eg. Say we just want to format our greeting like this:

def fmt-greet [name: string] -> string {
  $"Hello ($name)"
}```

Then for another command that takes a greeting as input:

```sh
def print-greeting [greeting: string] {
  echo $"When you greet someone, you should say: '($greet)'"
}

# then to call it
print-greet (fmt-greet "Fred")

How to reproduce

This is just a documentation ommision. There is no steps to reproduce this bug. Just add the missing documentation.

Expected behavior

The documentation on the web site for the Nushell book and the command reference should be updated to include the optional return type syntax for defining custom commands. This should also be included in the help text for the 'def' keyword.

Screenshots

No response

Configuration

key	value
version	0.84.0
branch
commit_hash
build_os	macos-aarch64
build_target	aarch64-apple-darwin
rust_version	rustc 1.71.1 (eb26296b5 2023-08-03) (built from a source tarball)
cargo_version	cargo 1.71.2 (1a737af0c 2023-08-07)
build_time	2023-08-22 21:09:23 +00:00
build_rust_channel	release
allocator	standard

Additional context

No response

[kubouch]

I believe that currently, both input and output types are required, and also :. The parser currently is not tight enough and does not report wrongly typed input/output types. I believe the correct syntax should be

def square [x: int]: nothing -> int {
  $x * $x
}

or in the case of multiple possible input/output pairs:

def square [x: int]: [ nothing -> int, nothing -> string ] {
  if $x == 0 {
    "zero" 
  } else {
    $x * $x
  }
}

You can verify this with help square.

[edhowland]

Ok, but none of the documentation I listed above mentions any of that. I agree that comment should exclude the point thatn being passed to another function that takes a particulartype. I think that the documentation should explicitly describe all of the of the 'def' keyword in all of its forms. What is the 'nothing' and the '[]: ' does not seem to work for 0.84.0 :
Error: nu::parser::parse_mismatch

× Parse mismatch during operation.
╭─[entry nushell/nushell#1:1:1]
1 │ def foo []: nothing {
· ▲
· ╰── expected arrow (->)
2 │ 1
╰────
syntax

[lordkekz]

I agree that the documentation should be updated to reflect the newly available syntax.
The web documentation lives in nushell/nushell.github.io btw.
Maybe this issue belongs more in that repo than here?

[kubouch]

Yes, definitely the docs need to be updated, I was just clarifying the syntax. The issue could live in https://github.com/nushell/nushell.github.io but here is also OK because we should update the output of help def to show this syntax.

@edhowland nothing is the input type (i.e., the type of the value piped in). The syntax is input_type -> output_type. Both must be present, that's why you got the error about missing arrow. The [] denotes that a command can have multiple input/output type pairs. In my second example, the square command does not take any piped input but can output either an integer, or a string.

[OrionOth]

With #1167, this should now be halfway done; while not documented in the def command documentation, it is documented in command_signatures.md. I think in the future, that documentation page should be integrated with other parts of the documentation; probably as part of a larger documentation restructuring.