[docs] Update cleos net commands and net plugin description #10360
Conversation
There was a problem hiding this comment.
For the net_api_plugin description change:
I think you have added the sentence in the wrong place. It should come after describing what the net plugin api is. The emphasis is now on the ability of bp's to manage their connections rather than what it is / does.
Also is it only for producing nodes?
| ## Description | ||
| Start a new connection to a peer | ||
| Start a new connection to a specified peer. This command allows an operator's node to connect to another peer without restarting the node. |
There was a problem hiding this comment.
passive?
This command allows an operator's node to connect to another peer without restarting the node.
to
Use this command to
There was a problem hiding this comment.
i.e. Use this command to connect to a peer without restarting the node.
There was a problem hiding this comment.
Point taken, but I want to highlight the fact that this command is particularly useful for node operators. "Use this command" for a generic user won't stress this fact. Therefore, to achieve this and make it active voice I changed to: "A node operator can use this command..."
| ## Examples | ||
| The following examples demonstrate how to use the `cleos net connect` command: | ||
|
|
||
| * Instruct default local node (listening at default http address `http://127.0.0.1:8888`) to connect to peer node listening at p2p address `localhost:9022`: |
There was a problem hiding this comment.
Should the examples be numbered rather than bulleted?
There was a problem hiding this comment.
I thought bullets were used when sequence doesn't matter - the case in point. If we want to identify the examples, then I think we should create explicit subtitles; e.g. Example 1, Example 2, etc. because numbered bullets in a list are used for a different purpose. @bobgt ?
There was a problem hiding this comment.
This is a good scenario.
If we use numbered list here, it may give a quick illusion that it's a procedure. So numbered list won't be a good fit.
If we go with bullets, it's not inappropriate but the 2 examples are not standing out clearly.
I would go with the explicit subtitles, L3 Headers:
Example 1
Instruct default local node (listening at default http address http://127.0.0.1:8888) to connect to peer node listening at p2p address localhost:9022:
cleos net connect localhost:9022Output:
"added connection"Example 2
I will consult with Virginia and update the Command Reference template. Thanks for flagging this!
| ## Description | ||
| close an existing connection | ||
| Close an existing connection to a specified peer. This command allows an operator's node to disconnect from another peer without restarting the node. |
There was a problem hiding this comment.
Agin should this be Use this command to ....
There was a problem hiding this comment.
Updated to: "A node operator can use this command..."
| ## Examples | ||
| The following examples demonstrate how to use the `cleos net disconnect` command: | ||
|
|
||
| * Instruct default local node (listening at default http address `http://127.0.0.1:8888`) to disconnect from peer node listening at p2p address `localhost:9022`: |
| ## Description | ||
| status of all existing peers | ||
| Returns a list with the status of all peer connections. This command allows a node operator to check the status of a node's peer connections. |
There was a problem hiding this comment.
Should it be Use this command to ....
| ## Examples | ||
| The following examples demonstrate how to use the `cleos net peers` command: | ||
|
|
||
| * List the status of all peer connections for a local node listening at http address `http://127.0.0.1:8001`: |
| ## Description | ||
| status of existing connection | ||
| Returns the status of a connected peer. This command allows a node operator to check the status of a node's connected peer. |
|
|
||
| * List the status of a connected peer listening at p2p address `localhost:9001` for a local node listening at http address `http://127.0.0.1:8002`: |
| ``` | ||
| **Output** | ||
| ### Positionals | ||
| * `host` _TEXT_ REQUIRED - The hostname:port to query status of connection. |
There was a problem hiding this comment.
Full stop at end ... template indicate this list doesn't have them
There was a problem hiding this comment.
Removed trailing period. Indeed, parameter descriptions will mainly consist of non-full sentences, so a trailing period is not needed. But if these were full sentences, a period is required.
| The following information shows the different positionals and options you can use with the `cleos net connect` command: | ||
|
|
||
| ### Positionals | ||
| * `host` _TEXT_ REQUIRED - The hostname:port to connect to. |
There was a problem hiding this comment.
Full stop at end ... template indicate this list doesn't have them
| The following information shows the different positionals and options you can use with the `cleos net disconnect` command: | ||
|
|
||
| ### Positionals | ||
| * `host` _TEXT_ REQUIRED - The hostname:port to disconnect from. |
There was a problem hiding this comment.
Full stop at end ... template indicate this list doesn't have them
| * `host` _TEXT_ REQUIRED - The hostname:port to disconnect from. | ||
|
|
||
| ### Options | ||
| * `-h,--help` - Print this help message and exit. |
There was a problem hiding this comment.
Full stop at end ... template indicate this list doesn't have them
| * `host` _TEXT_ REQUIRED - The hostname:port to connect to. | ||
|
|
||
| ### Options | ||
| * `-h,--help` - Print this help message and exit. |
There was a problem hiding this comment.
Full stop at end ... template indicate this list doesn't have them
|
|
||
| **Command** | ||
| ### Positionals | ||
| * `host` _TEXT_ REQUIRED - The hostname:port to disconnect from. |
There was a problem hiding this comment.
Full stop at end ... template indicate this list doesn't have them
| * `host` _TEXT_ REQUIRED - The hostname:port to disconnect from. | ||
|
|
||
| ### Options | ||
| * `-h,--help` - Print this help message and exit. |
There was a problem hiding this comment.
Full stop at end ... template indicate this list doesn't have them
| ```console | ||
| Usage: cleos net status host | ||
| ### Options | ||
| * `-h,--help` - Print this help message and exit. |
There was a problem hiding this comment.
Full stop at end ... template indicate this list doesn't have them
Point taken. I swapped the order of the sentences. Also removed "producing" since the net api can also be used on non-producing nodes. |
Change Description
Resolves devrel-1468 - update cleos net command reference with template
Resolves devrel-1080 (#9868) - cleos net peers refers to cleos net status instead
Change Type
Select ONE:
Testing Changes
Select ANY that apply:
Consensus Changes
API Changes
Documentation Additions