holm/nushell
1
1
Fork 0
forked from extern/nushell
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Change the usage misnomer to "description" (#13598)

Browse Source 
# Description
    
The meaning of the word usage is specific to describing how a command
function is *used* and not a synonym for general description. Usage can
be used to describe the SYNOPSIS or EXAMPLES sections of a man page
where the permitted argument combinations are shown or example *uses*
are given.
Let's not confuse people and call it what it is a description.

Our `help` command already creates its own *Usage* section based on the
available arguments and doesn't refer to the description with usage.

# User-Facing Changes

`help commands` and `scope commands` will now use `description` or
`extra_description`
`usage`-> `description`
`extra_usage` -> `extra_description`

Breaking change in the plugin protocol:

In the signature record communicated with the engine.
`usage`-> `description`
`extra_usage` -> `extra_description`

The same rename also takes place for the methods on
`SimplePluginCommand` and `PluginCommand`

# Tests + Formatting
- Updated plugin protocol specific changes
# After Submitting
- [ ] update plugin protocol doc
This commit is contained in:
Stefan Holderbach
2024-08-22 12:02:08 +02:00
committed by GitHub
parent 3ab9f0b90a
commit 95b78eee25
597 changed files with 1085 additions and 1039 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
crates/nu-engine/src/scope.rs
View File

@ -109,12 +109,12 @@ impl<'e, 's> ScopeData<'e, 's> {
"name" => Value::string(String::from_utf8_lossy(command_name), span),
"category" => Value::string(signature.category.to_string(), span),
"signatures" => self.collect_signatures(&signature, span),
"usage" => Value::string(decl.usage(), span),
"description" => Value::string(decl.description(), span),
"examples" => Value::list(examples, span),
"type" => Value::string(decl.command_type().to_string(), span),
"is_sub" => Value::bool(decl.is_sub(), span),
"creates_scope" => Value::bool(signature.creates_scope, span),
"extra_usage" => Value::string(decl.extra_usage(), span),
"extra_description" => Value::string(decl.extra_description(), span),
"search_terms" => Value::string(decl.search_terms().join(", "), span),
"decl_id" => Value::int(**decl_id as i64, span),
};
@ -332,7 +332,7 @@ impl<'e, 's> ScopeData<'e, 's> {
if decl.is_known_external() {
let record = record! {
"name" => Value::string(String::from_utf8_lossy(command_name), span),
"usage" => Value::string(decl.usage(), span),
"description" => Value::string(decl.description(), span),
"decl_id" => Value::int(**decl_id as i64, span),
};
@ -366,7 +366,7 @@ impl<'e, 's> ScopeData<'e, 's> {
record! {
"name" => Value::string(String::from_utf8_lossy(&decl_name), span),
"expansion" => Value::string(expansion, span),
"usage" => Value::string(alias.usage(), span),
"description" => Value::string(alias.description(), span),
"decl_id" => Value::int(decl_id as i64, span),
"aliased_decl_id" => aliased_decl_id,
},
@ -470,9 +470,9 @@ impl<'e, 's> ScopeData<'e, 's> {
sort_rows(&mut export_submodules);
sort_rows(&mut export_consts);
let (module_usage, module_extra_usage) = self
let (module_desc, module_extra_desc) = self
.engine_state
.build_module_usage(*module_id)
.build_module_desc(*module_id)
.unwrap_or_default();
Value::record(
@ -484,8 +484,8 @@ impl<'e, 's> ScopeData<'e, 's> {
"submodules" => Value::list(export_submodules, span),
"constants" => Value::list(export_consts, span),
"has_env_block" => Value::bool(module.env_block.is_some(), span),
"usage" => Value::string(module_usage, span),
"extra_usage" => Value::string(module_extra_usage, span),
"description" => Value::string(module_desc, span),
"extra_description" => Value::string(module_extra_desc, span),
"module_id" => Value::int(*module_id as i64, span),
},
span,