Skip to content
This repository has been archived by the owner on Aug 2, 2022. It is now read-only.

[docs] Update cleos net commands and net plugin description #10360

Merged
merged 6 commits into from
May 18, 2021
Merged

[docs] Update cleos net commands and net plugin description #10360

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b3d9e74
improve net_api_plugin description :doc
May 14, 2021
7895e3f
improve cleos net connect command reference :doc
May 14, 2021
cc60a63
improve cleos net disconnect command reference :doc
May 14, 2021
d47b914
improve cleos net peers command reference :doc
May 14, 2021
6de4f79
improve cleos net status command reference :doc
May 14, 2021
b04ee3f
add edits from PH's review :doc
May 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/01_nodeos/03_plugins/net_api_plugin/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
## Description

The `net_api_plugin` exposes functionality from the `net_plugin` to the RPC API interface managed by the `http_plugin`.
The `net_api_plugin` allows node operators to manage the p2p connections of a producing node. The `net_api_plugin` exposes functionality from the `net_plugin` to the RPC API interface managed by the `http_plugin`.

The `net_api_plugin` provides four RPC API endpoints:

Expand Down
55 changes: 47 additions & 8 deletions docs/02_cleos/03_command-reference/net/connect.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,56 @@
## Command
```sh
cleos net connect [OPTIONS] host
```

**Where:**
* [OPTIONS] = See **Options** in the [**Command Usage**](command-usage) section below.
* host = The hostname:port to connect to.

**Note:** The arguments and options enclosed in square brackets are optional.

## 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

passive?

This command allows an operator's node to connect to another peer without restarting the node.

to

Use this command to

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i.e. Use this command to connect to a peer without restarting the node.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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..."


## Command Usage
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Full stop at end ... template indicate this list doesn't have them

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed.


### Options
* `-h,--help` - Print this help message and exit.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Full stop at end ... template indicate this list doesn't have them

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed.


## Requirements
Make sure you meet the following requirements:

**Command**
* Install the currently supported version of `cleos`.
[[info | Note]]
| `cleos` is bundled with the EOSIO software. [Installing EOSIO](../../../00_install/index.md) will also install the `cleos` and `keosd` command line tools.
* You have access to a producing node instance with the [`net_api_plugin`](../../../01_nodeos/03_plugins/net_api_plugin/index.md) loaded.

## 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`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the examples be numbered rather than bulleted?

Copy link
Contributor Author

@lparisc lparisc May 14, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:9022

Output:

"added connection"

Example 2

I will consult with Virginia and update the Command Reference template. Thanks for flagging this!

```sh
cleos net connect
cleos net connect localhost:9022
```
**Output:**
```console
"added connection"
```

**Output**

* Instruct local node listening at http address `http://127.0.0.1:8001` to connect to peer node listening at p2p address `localhost:9022`:
```sh
cleos -u http://127.0.0.1:8001 net connect localhost:9022
```
**Output:**
```console
Usage: cleos net connect host
"added connection"
```

Positionals:
host TEXT The hostname:port to connect to.
**Note:** If any of the above commands are re-executed, `cleos` returns the following message as expected:
```console
"already connected"
```