`help` pages should unambiguously state the type signatures of each command

[webbedspace]

Related problem

I feel like the current layout of help pages is too manpage-inspired and doesn't take advantage of Nu's data-typing strengths. In particular, the fact that they often don't directly state what type of data should be piped into them, or what they pipe out, is a little annoying.

Here's an example. The only bit that tells you what data parse accepts and outputs is a prose sentence at the top.

Parse columns from string data using a simple pattern.

Search terms: pattern, match

Usage:
  > parse {flags} <pattern>

Flags:
  -h, --help - Display this help message
  -r, --regex - use full regex syntax for patterns

Parameters:
  pattern <String>: the pattern to match. Eg) "{foo}: {bar}"

Describe the solution you'd like

What I'd like is for there to be a vaguely describe-inspired signature added into here, like:

<string> | parse <string> | <table>

Other commands would have signatures like these (note: examples may not be entirely accurate, and symbols for "optional" and "rest" are up for debate):

<nothing> | ls <string>? | table<name: string, type: string, size: filesize, modified: date>

<record or table> | upsert <string> <any> | <record or table>

<any> | each <block> | <any>

<nothing> | touch <path> ...<path> | <nothing>

Note that {flags} isn't listed because anything can take flags (even if the only accepted one is --help)

Describe alternatives you've considered

No response

Additional context and details

No response

[fdncred]

Thanks for the comment. input_type and output_type aren't fully fleshed out yet, so your point is valid. I don't think we'll be able to do what you're talking about until that gets finished. they could indeed use some improvements, if I'm understanding you correctly. This is another thing @dandavison and I were talking about yesterday. For more details on command signatures you should look at $nu.scope.commands.

[jokeyrhyme]

Yeah, it would be super handy to know whether a command works in a pipeline and/or whether it takes arguments

$nu.scope.commands doesn't seem to contain this information

We were just discussing this here https://www.reddit.com/r/Nushell/comments/y7pges/how_can_i_pipe_an_id_from_ps_into_kill/?utm_source=share&utm_medium=web2x&context=3 and wondered whether there was a way to pass the definition of a command into describe, maybe?

If we try ls | describe it is calling ls instead of passing it as a value :shrug:

[webbedspace]

describe is not the correct place for command descriptions. That is what help is for. describe seems(?) to be the language's equivalent of ~~JS's typeof~~ Python's type() - a service which provides type-checking for any type.

[dandavison]

I really appreciate this write-up. I agree with the sentiment (that input and output types need to be much better documented) and I think that the proposed format is really nice. @webbedspace one question about the format I guess is: if the language gains return type syntax on command definitions, perhaps we want the help format to mirror the return type syntax? But anyway, we can probably change the help format down the line since AIUI it won't be intended to be machine readable; for that we'd have a column in help commands and/or $nu.scope.commands.

I've started a PR https://github.com/nushell/nushell/pull/6796 which aims to capture the input/output type information needed to implement this issue's suggestions. @webbedspace if you had time to comment (or even collaborate) on that one that would of course be great.

[fdncred]

As Dan's #6796 gets closer to landing, I think it would be good to start figuring this part out.

So, this is just throwing out ideas.

As said before, it would be good to have this input/output type information available when you do help blah. I'm not exactly sure what that should look like but here's a thought. If we take a simple one describe, we could describe it like the other areas

> help describe
Describe the type and structure of the value(s) piped in.

Search terms: type, typeof, info, structure

Usage:
  > describe

Flags:
  -h, --help - Display the help message for this command

Input: Any
Output: String

Examples:
  Describe the type of a string
  > 'hello' | describe

or one that's a little more complex like debug. The input output reads like the first item on the input line maps to the first item on the output line, and so on.

> help debug
Debug print the value(s) piped in.

Usage:
  > debug {flags}

Flags:
  -h, --help - Display the help message for this command
  -r, --raw - Prints the raw value representation

Input: List<Any>, Table, Any
Output: List<String>, List<String>, String

Examples:
  Print the value of a string
  > 'hello' | debug

  Print the value of a table
  > echo [[version patch]; [0.1.0 false] [0.1.1 true] [0.2.0 false]] | debug

Another option is more inline with @webbedspace's original idea where, instead of having the Input: and Output: like I show above, we have something more like this:

Input Type	command	Output Type
List<Any>	debug	List<String>
Table	debug	List<String>
Any	debug	String

Or a pseudo pipeline where --> just means that it outputs this type

List<Any> | debug --> List<String>
Table | debug --> List<String>
Any | debug --> String