Skip to content

Commit a59f444

Browse files
sholderbachsholderbach
authored
Fixup usage->description in plugin stuff (#1743)
* Fixup `usage`->`description` in plugin stuff Forgot to follow up nushell/nushell#13598 here. Supersede that part of closed #1724 * Fix table headers along similar lines * Fix whitespace in table header
1 parent 52b4dbc commit a59f444

File tree

2 files changed

+26
-26
lines changed

2 files changed

+26
-26
lines changed

‎contributor-book/plugin_protocol_reference.md‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ The engine **may** send a [`Goodbye`](#goodbye) message to the plugin indicating
3939

4040
After the encoding type has been decided, both the engine and plugin **must** send a `Hello` message containing relevant version and protocol support information.
4141

42-
| Field | Type | Usage |
42+
| Field | Type | Description |
4343
| ------------ | ------ | ------------------------------------------------------------------------------------- |
4444
| **protocol** | string | **Must** be `"nu-plugin"`. |
4545
| **version** | string | The engine's version, or the target version of Nu that the plugin supports. |
@@ -125,7 +125,7 @@ Example:
125125

126126
Tell the plugin to run a command. The argument is the following map:
127127

128-
| Field | Type | Usage |
128+
| Field | Type | Description |
129129
| --------- | ------------------------------------------- | ----------------------------------------------------- |
130130
| **name** | string | The name of the command to run |
131131
| **call** | [`EvaluatedCall`](#evaluatedcall) | Information about the invocation, including arguments |
@@ -135,7 +135,7 @@ Tell the plugin to run a command. The argument is the following map:
135135

136136
`EvaluatedCall` is a map:
137137

138-
| Field | Type | Usage |
138+
| Field | Type | Description |
139139
| -------------- | ------------------------------------------------- | ------------------------------------------------------- |
140140
| **head** | [`Span`](#span) | The position of the beginning of the command execution. |
141141
| **positional** | [`Value`](#value) array | Positional arguments. |
@@ -634,7 +634,7 @@ Example:
634634

635635
A successful response to a [`Metadata` plugin call](#metadata-plugin-call). The body contains fields that describe the plugin, none of which are required:
636636

637-
| Field | Type | Usage |
637+
| Field | Type | Description |
638638
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------- |
639639
| **version** | string? | The version of the plugin (not the protocol!). [SemVer](https://semver.org) is recommended, but not required. |
640640

@@ -668,8 +668,8 @@ Example:
668668
{
669669
"sig": {
670670
"name": "len",
671-
"usage": "calculates the length of its input",
672-
"extra_usage": "",
671+
"description": "calculates the length of its input",
672+
"extra_description": "",
673673
"search_terms": [],
674674
"required_positional": [],
675675
"optional_positional": [],
@@ -762,7 +762,7 @@ Example:
762762

763763
Plugins can make engine calls during execution of a [call](#call). The body is a map with the following keys:
764764

765-
| Field | Type | Usage |
765+
| Field | Type | Description |
766766
| ----------- | ------------ | --------------------------------------------------------------------------------------- |
767767
| **context** | integer | The ID of the [call](#call) that this engine call relates to. |
768768
| **id** | integer | A unique ID for this engine call, in order to send the [response](#enginecallresponse). |
@@ -975,7 +975,7 @@ Example:
975975

976976
Pass a [`Closure`](#closure) and arguments to the engine to be evaluated. Returns a [`PipelineData` response](#pipelinedata-engine-call-response) if successful with the output of the closure, which may be a stream.
977977

978-
| Field | Type | Usage |
978+
| Field | Type | Description |
979979
| ------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
980980
| **closure** | spanned [`Closure`](#closure) | The closure to call, generally from a [`Value`](#value). |
981981
| **positional** | [`Value`](#value) array | Positional arguments for the closure. |
@@ -1048,7 +1048,7 @@ Example:
10481048

10491049
Pass a command's declaration ID (found via [`FindDecl`](#finddecl-engine-call)) and arguments to the engine to be called. Returns a [`PipelineData` response](#pipelinedata-engine-call-response) if successful with the output of the command, which may be a stream.
10501050

1051-
| Field | Type | Usage |
1051+
| Field | Type | Description |
10521052
| ------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
10531053
| **decl_id** | unsigned integer | The ID of the declaration to call. |
10541054
| **call** | [`EvaluatedCall`](#evaluatedcall) | Arguments and head span for the call. |
@@ -2082,7 +2082,7 @@ Represents data types that extend the base nushell types with custom functionali
20822082

20832083
`Custom` values for plugins **may** only contain the following content map:
20842084

2085-
| Field | Type | Usage |
2085+
| Field | Type | Description |
20862086
| ------------------ | ---------- | ----------------------------------------------------------------------------------------- |
20872087
| **type** | string | **Must** be `"PluginCustomValue"`. |
20882088
| **name** | string | The human-readable name of the custom value emitted by the plugin. |
@@ -2138,7 +2138,7 @@ Structs are encoded as maps of their fields, without the name of the struct.
21382138

21392139
Describes a region of code in the engine's memory, used mostly for providing diagnostic error messages to the user with context about where a value that caused an error came from.
21402140

2141-
| Field | Type | Usage |
2141+
| Field | Type | Description |
21422142
| --------- | ------- | ---------------------------------------------- |
21432143
| **start** | integer | The index of the first character referenced. |
21442144
| **end** | integer | The index after the last character referenced. |
@@ -2147,7 +2147,7 @@ Describes a region of code in the engine's memory, used mostly for providing dia
21472147

21482148
Describes either a single value, or the beginning of a stream.
21492149

2150-
| Variant | Usage |
2150+
| Variant | Description |
21512151
| ------------------------------------------ | ---------------------------------------- |
21522152
| [`Empty`](#empty-header-variant) | No values produced; an empty stream. |
21532153
| [`Value`](#value-header-variant) | A single value |
@@ -2190,7 +2190,7 @@ Starts a list stream. Expect [`Data`](#data) messages of the `List` variant with
21902190

21912191
Contains <a name="liststreaminfo">`ListStreamInfo`</a>, a map:
21922192

2193-
| Field | Type | Usage |
2193+
| Field | Type | Description |
21942194
| -------- | --------------- | ------------------------------------------------- |
21952195
| **id** | integer | The stream identifier |
21962196
| **span** | [`Span`](#span) | The source code reference that caused the stream. |
@@ -2213,7 +2213,7 @@ Example:
22132213

22142214
Starts a byte stream. Expect [`Data`](#data) messages of the `Raw` variant with the referenced ID.
22152215

2216-
| Field | Type | Usage |
2216+
| Field | Type | Description |
22172217
| -------- | ----------------------------------- | ------------------------------------------------- |
22182218
| **id** | integer | The stream identifier |
22192219
| **span** | [`Span`](#span) | The source code reference that caused the stream. |
@@ -2250,7 +2250,7 @@ Example:
22502250

22512251
A flexible, generic error type, with any number of labeled spans.
22522252

2253-
| Field | Type | Usage |
2253+
| Field | Type | Description |
22542254
| ---------- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
22552255
| **msg** | string | The main error message to show at the top of the error. |
22562256
| **labels** | `ErrorLabel` array? | Spans and messages to label the error in the source code. |
@@ -2261,7 +2261,7 @@ A flexible, generic error type, with any number of labeled spans.
22612261

22622262
Most of the fields are not required - only `msg` must be present. `ErrorLabel` (in the `labels` array) is as follows:
22632263

2264-
| Field | Type | Usage |
2264+
| Field | Type | Description |
22652265
| -------- | --------------- | ----------------------------------------------------------- |
22662266
| **text** | string | The message for the label. |
22672267
| **span** | [`Span`](#span) | The span in the source code that the label should point to. |

‎contributor-book/plugins.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ impl SimplePluginCommand for Len {
9090
"len"
9191
}
9292

93-
fn usage(&self) -> &str {
93+
fn description(&self) -> &str {
9494
"calculates the length of its input"
9595
}
9696

@@ -160,7 +160,7 @@ impl SimplePluginCommand for Len {
160160
"len"
161161
}
162162

163-
fn usage(&self) -> &str {
163+
fn description(&self) -> &str {
164164
"calculates the length of its input"
165165
}
166166

@@ -173,7 +173,7 @@ impl SimplePluginCommand for Len {
173173
}
174174
```
175175

176-
There are a few methods required for this implementation. We first define the `name` of the command, which is what the user will type at the prompt or in their script to run the command. The `usage` is also required, which is a short documentation string for users to know what the command does, and is displayed along with completions and in `help`. Finally, we define the `signature`, which specifies arguments and types for the command.
176+
There are a few methods required for this implementation. We first define the `name` of the command, which is what the user will type at the prompt or in their script to run the command. The `description` is also required, which is a short documentation string for users to know what the command does, and is displayed along with completions and in `help`. Finally, we define the `signature`, which specifies arguments and types for the command.
177177

178178
We tell Nu that the name is "len", give it a basic description for `help` to display and declare that we expect to be passed a string and will return an integer.
179179

@@ -432,7 +432,7 @@ impl SimplePluginCommand for Motd {
432432
"motd"
433433
}
434434

435-
fn usage(&self) -> &str {
435+
fn description(&self) -> &str {
436436
"Message of the day"
437437
}
438438

@@ -505,7 +505,7 @@ impl PluginCommand for MyEach {
505505
"my-each"
506506
}
507507

508-
fn usage(&self) -> &str {
508+
fn description(&self) -> &str {
509509
"Run closure on each element of a list"
510510
}
511511

@@ -899,7 +899,7 @@ $ ./target/release/nu_plugin_len --stdio
899899
json{"Hello":{"protocol":"nu-plugin","version":"0.90.2","features":[]}}
900900
{"Hello":{"protocol":"nu-plugin","version":"0.90.2","features":[]}}
901901
{"Call":[0,"Signature"]}
902-
{"CallResponse":[0, {"Signature":[{"sig":{"name":"len","usage":"calculates the length of its input","extra_usage":"","search_terms":[],"required_positional":[],"optional_positional":[],"rest_positional":null,"vectorizes_over_list":false,"named":[{"long":"help","short":"h","arg":null,"required":false,"desc":"Display the help message for this command","var_id":null,"default_value":null}],"input_type":"String","output_type":"Int","input_output_types":[],"allow_variants_without_examples":false,"is_filter":false,"creates_scope":false,"allows_unknown_args":false,"category":"Default"},"examples":[]}]}]}
902+
{"CallResponse":[0, {"Signature":[{"sig":{"name":"len","description":"calculates the length of its input","extra_description":"","search_terms":[],"required_positional":[],"optional_positional":[],"rest_positional":null,"vectorizes_over_list":false,"named":[{"long":"help","short":"h","arg":null,"required":false,"desc":"Display the help message for this command","var_id":null,"default_value":null}],"input_type":"String","output_type":"Int","input_output_types":[],"allow_variants_without_examples":false,"is_filter":false,"creates_scope":false,"allows_unknown_args":false,"category":"Default"},"examples":[]}]}]}
903903
```
904904

905905
The plugin prints its signature serialized as JSON. We'll reformat for readability.
@@ -910,8 +910,8 @@ The plugin prints its signature serialized as JSON. We'll reformat for readabili
910910
{
911911
"sig": {
912912
"name": "len",
913-
"usage": "calculates the length of its input",
914-
"extra_usage": "",
913+
"description": "calculates the length of its input",
914+
"extra_description": "",
915915
"search_terms": [],
916916
"required_positional": [],
917917
"optional_positional": [],
@@ -1020,8 +1020,8 @@ def signature():
10201020
return {
10211021
"sig": {
10221022
"name": "len",
1023-
"usage": "calculates the length of its input",
1024-
"extra_usage": "",
1023+
"description": "calculates the length of its input",
1024+
"extra_description": "",
10251025
"search_terms": [],
10261026
"required_positional": [],
10271027
"optional_positional": [],

0 commit comments

Comments
 (0)