Add more examples to help use

[TrMen]

Description

The members parameter of use is specified as type any, but it's really a string or list of strings or *. So add some examples that mention what you can specify for members.

Also mention help modules and help std, since you probably want to use the standard library or another defined modules.

Sidenote: I tried to run the examples for use as tests like is done for the other commands. That panics with missing module command. I assume this is known.

User-Facing Changes

help use now looks like this:

Use definitions from a module, making them available in your shell.

See `help std` for the standard library module.
See `help modules` to list all available modules.

This command is a parser keyword. For details, check:
  https:https://www.nushell.sh/book/thinking_in_nu.html

Usage:
  > use <module> (members)

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

Parameters:
  module <string>: Module or module file
  (optional) members <any>: Which members of the module to import

Examples:
  Define a custom command in a module and call it
  > module spam { export def foo [] { "foo" } }; use spam foo; foo
  foo

  Define a custom command that participates in the environment in a module and call it
  > module foo { export def-env bar [] { let-env FOO_BAR = "BAZ" } }; use foo bar; bar; $env.FOO_BAR
  BAZ

  Use a plain module name to import its definitions qualified by the module name
  > module spam { export def foo [] { "foo" }; export def bar [] { "bar" } }; use spam; (spam foo) + (spam bar)
  foobar

  Specify * to use all definitions in a module
  > module spam { export def foo [] { "foo" }; export def bar [] { "bar" } }; use spam *; (foo) + (bar)
  foobar

  To use commands with spaces, like subcommands, surround them with quotes
  > module spam { export def 'foo bar' [] { "baz" } }; use spam 'foo bar'; foo bar
  baz

  To use multiple definitions from a module, wrap them in a list
  > module spam { export def foo [] { "foo" }; export def 'foo bar' [] { "baz" } }; use spam ['foo', 'foo bar']; (foo) + (foo bar)
  foobaz

[fdncred]

I really like the idea but I have concerns about using use std in examples right now. It's so fluid that we could quickly get into a place where these examples fail testing because we rename something. I'm wondering if there's a better way to demonstrate examples that are testable without using use std?

[TrMen]

Sure, that seems reasonable. I've updated the examples to define their own modules and be self-contained. It's a bit verbose, but maybe better anyway since you see what kind of definitions we are useing, rather than something opaque from std you might not be familar with. I've also updated the PR description with the rendered output.

I kept the hint to use help std, since I think the very concept of a standard library probably won't go away. That's probably the vast majority of what users want to use. I can remove it as well though if you prefer.

If you prefer any changes in wording, also feel free to just make the change.

[codecov]

Codecov Report

Merging #9024 (57a70ac) into main (ffb9ab9) will decrease coverage by 0.02%.
The diff coverage is 100.00%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9024      +/-   ##
==========================================
- Coverage   68.76%   68.74%   -0.02%     
==========================================
  Files         640      640              
  Lines      101390   101413      +23     
==========================================
+ Hits        69718    69721       +3     
- Misses      31672    31692      +20     

Impacted Files	Coverage Δ
crates/nu-cmd-lang/src/core_commands/use_.rs	86.71% <100.00%> (+2.90%)	⬆️

... and 3 files with indirect coverage changes

[fdncred]

Thanks for helping out. Looks good!