chore: update dfx canister documentation

docs/cli-reference/dfx-wallet.md

@@ -88,7 +88,7 @@ You can use the following options with the `dfx canister call` command.
 
 |Option |Description|
 --------|------------|
-|`--network <network>` |Specifies the environment (e.g., {platform} or testnet) of the controller you want to add.
+|`--network <network>` |Specifies the environment (e.g., Internet Computer or testnet) of the controller you want to add.
 
 ### Arguments
 

src/dfx/src/commands/canister/call.rs

@@ -39,7 +39,7 @@ pub struct CanisterCallOpts {
     #[clap(long)]
     r#async: bool,
 
-    /// Sends a query request to a canister.
+    /// Sends a query request to a canister instead of an update request.
     #[clap(long, conflicts_with("async"))]
     query: bool,
 
@@ -51,7 +51,7 @@ pub struct CanisterCallOpts {
     #[clap(conflicts_with("random"))]
     argument: Option<String>,
 
-    /// Specifies the config for generating random argument.
+    /// Specifies the config for generating random arguments.
     #[clap(long, conflicts_with("argument"))]
     random: Option<String>,
 
@@ -66,6 +66,7 @@ pub struct CanisterCallOpts {
 
     /// Specifies the amount of cycles to send on the call.
     /// Deducted from the wallet.
+    /// Requires --wallet as a flag to `dfx canister`.
     #[clap(long, validator(cycle_amount_validator))]
     with_cycles: Option<String>,
 

src/dfx/src/commands/canister/create.rs

@@ -20,8 +20,7 @@ use ic_agent::Identity as _;
 use ic_types::principal::Principal as CanisterId;
 use slog::info;
 
-/// Creates an empty canister on the Internet Computer and
-/// associates the Internet Computer assigned Canister ID to the canister name.
+/// Creates an empty canister and associates the assigned Canister ID to the canister name.
 #[derive(Parser)]
 pub struct CanisterCreateOpts {
     /// Specifies the canister name. Either this or the --all flag are required.
@@ -46,7 +45,7 @@ pub struct CanisterCreateOpts {
     compute_allocation: Option<String>,
 
     /// Specifies how much memory the canister is allowed to use in total.
-    /// This should be a value in the range [0..12 GiB]
+    /// This should be a value in the range [0..12 GiB].
     /// A setting of 0 means the canister will have access to memory on a “best-effort” basis:
     /// It will only be charged for the memory it uses, but at any point in time may stop running
     /// if it tries to allocate more memory when there isn’t space available on the subnet.

src/dfx/src/commands/canister/delete.rs

@@ -36,7 +36,7 @@ const DANK_PRINCIPAL: Principal =
 const WITHDRAWAL_COST: u128 = 10_000_000_000; // Emperically estimated.
 const MAX_MEMORY_ALLOCATION: u64 = 8589934592;
 
-/// Deletes a canister on the Internet Computer network.
+/// Deletes a currently stopped canister.
 #[derive(Parser)]
 pub struct CanisterDeleteOpts {
     /// Specifies the name of the canister to delete.
@@ -51,7 +51,7 @@ pub struct CanisterDeleteOpts {
     #[clap(long)]
     no_withdrawal: bool,
 
-    /// Withdraw cycles from canister(s) to canister/wallet before deleting.
+    /// Withdraw cycles from canister(s) to the specified canister/wallet before deleting.
     #[clap(long, conflicts_with("no-withdrawal"))]
     withdraw_cycles_to_canister: Option<String>,
 

src/dfx/src/commands/canister/info.rs

@@ -10,10 +10,10 @@ use ic_types::Principal;
 use serde_cbor::Value;
 use std::convert::TryFrom;
 
-/// Get the hash of a canister’s WASM module and its current controller in a certified way.
+/// Get the hash of a canister’s WASM module and its current controller.
 #[derive(Parser)]
 pub struct InfoOpts {
-    /// Specifies the name or id of the canister to get its certified canister information.
+    /// Specifies the name or id of the canister to get its canister information.
     canister: String,
 }
 

src/dfx/src/commands/canister/install.rs

@@ -18,7 +18,7 @@ use std::fs;
 use std::path::PathBuf;
 use std::str::FromStr;
 
-/// Deploys compiled code as a canister on the Internet Computer.
+/// Installs compiled code in a canister.
 #[derive(Parser, Clone)]
 pub struct CanisterInstallOpts {
     /// Specifies the canister to deploy. You must specify either canister name/id or the --all option.
@@ -49,7 +49,7 @@ pub struct CanisterInstallOpts {
     #[clap(long, requires("argument"), possible_values(&["idl", "raw"]))]
     argument_type: Option<String>,
 
-    /// Specifies a particular WASM file to install, bypassing the dfx.json project system.
+    /// Specifies a particular WASM file to install, bypassing the dfx.json project settings.
     #[clap(long, conflicts_with("all"))]
     wasm: Option<PathBuf>,
 }

src/dfx/src/commands/canister/request_status.rs

@@ -14,7 +14,7 @@ use ic_agent::{AgentError, RequestId};
 use ic_types::Principal;
 use std::str::FromStr;
 
-/// Requests the status of a specified call from a canister.
+/// Requests the status of a call from a canister.
 #[derive(Parser)]
 pub struct RequestStatusOpts {
     /// Specifies the request identifier.

src/dfx/src/commands/canister/send.rs

@@ -12,7 +12,7 @@ use ic_types::Principal;
 use std::{fs::File, path::Path};
 use std::{io::Read, str::FromStr};
 
-/// Send a signed message
+/// Send a previously-signed message.
 #[derive(Parser)]
 pub struct CanisterSendOpts {
     /// Specifies the file name of the message

src/dfx/src/commands/canister/sign.rs

@@ -26,7 +26,7 @@ use std::path::Path;
 use std::str::FromStr;
 use std::time::SystemTime;
 
-/// Sign a canister call and generate message file in json
+/// Sign a canister call and generate message file.
 #[derive(Parser)]
 pub struct CanisterSignOpts {
     /// Specifies the name of the canister to call.
@@ -54,7 +54,7 @@ pub struct CanisterSignOpts {
     #[clap(long, requires("argument"), possible_values(&["idl", "raw"]))]
     r#type: Option<String>,
 
-    /// Specifies how long will the message be valid in seconds, default to be 300s (5 minutes)
+    /// Specifies how long the message will be valid in seconds, default to be 300s (5 minutes)
     #[clap(long, default_value("5m"))]
     expire_after: String,
 

src/dfx/src/commands/canister/start.rs

@@ -11,7 +11,7 @@ use ic_types::Principal;
 use slog::info;
 use std::time::Duration;
 
-/// Starts a canister on the Internet Computer network.
+/// Starts a stopped canister.
 #[derive(Parser)]
 pub struct CanisterStartOpts {
     /// Specifies the name or id of the canister to start. You must specify either a canister name/id or the --all flag.

src/dfx/src/commands/canister/status.rs

@@ -12,7 +12,7 @@ use ic_types::Principal;
 use slog::info;
 use std::time::Duration;
 
-/// Returns the current status of the canister on the Internet Computer network: Running, Stopping, or Stopped.
+/// Returns the current status of a canister: Running, Stopping, or Stopped.
 #[derive(Parser)]
 pub struct CanisterStatusOpts {
     /// Specifies the name of the canister to return information for.

src/dfx/src/commands/canister/stop.rs

@@ -11,7 +11,7 @@ use ic_types::Principal;
 use slog::info;
 use std::time::Duration;
 
-/// Stops a canister that is currently running on the Internet Computer network.
+/// Stops a currently running canister.
 #[derive(Parser)]
 pub struct CanisterStopOpts {
     /// Specifies the name or id of the canister to stop.

src/dfx/src/commands/canister/uninstall_code.rs

@@ -11,7 +11,8 @@ use ic_types::Principal;
 use slog::info;
 use std::time::Duration;
 
-/// Uninstalls a canister, removing its code and state, on the Internet Computer network.
+/// Uninstalls a canister, removing its code and state.
+/// Does not delete the canister.
 #[derive(Parser)]
 pub struct UninstallCodeOpts {
     /// Specifies the name or id of the canister to uinstall.

src/dfx/src/commands/canister/update_settings.rs

@@ -34,9 +34,11 @@ pub struct UpdateSettingsOpts {
     #[clap(long, multiple_occurrences(true))]
     controller: Option<Vec<String>>,
 
+    /// Add a principal to the list of controllers of the canister.
     #[clap(long, multiple_occurrences(true), conflicts_with("controller"))]
     add_controller: Option<Vec<String>>,
 
+    /// Removes a principal from the list of controllers of the canister.
     #[clap(long, multiple_occurrences(true), conflicts_with("controller"))]
     remove_controller: Option<Vec<String>>,