Table of Contents
All the docstrings for the jsonrpc commands must adhere to this format so they can be parsed by the scripts which generate the documentation. The script is here if you want to make changes.
There are examples below for those who learn best that way, or who like copy-pasting.
Please note that the colons(:) are important.
First Line
The first line after the """ in the docstring is a short description of what the function does.
Subheading Usage:
It should start with the word "Usage:", then in the next line list out the command name, then the arguments(as prescribed by docopts library). It is of the following format
Usage:
command_name (<required_args>) [<optional_arg1> | --optional_arg1=<optional_arg1>]
[<optional_arg2> | --optional_arg2=<optional_arg2>]
Subheading Options:
It should start with the word "Options:", then in the next line
- If there are no arguments just write "None"
- Otherwise list out the command name followed by two dashes --, then ":", after that type of argument in parenthesis
(type)and short description of the argument after a blank space. Please list out all of the arguments be it required, optional or Boolean as it is required by the api. It is of the following format
Options:
--bool_arg : (bool) short description
--required_arg=<required_arg> : (type) short description
--optional_arg1=<optional_arg1> : (type) short description
--optional_arg2=<optional_arg2> : (type) short description
(Note: this ^ blank space is important)
Subheading Returns:
It should start with the word "Returns:", then from the next line list out the response signature that the command return. It is of the following format
Returns:
Response signature, it may be a list, dict, Boolean etc.
Example 1
"""
Get blob availability
Usage:
blob_availability (<blob_hash>) [<search_timeout> | --search_timeout=<search_timeout>]
[<blob_timeout> | --blob_timeout=<blob_timeout>]
Options:
--blob_hash=<blob_hash> : (str) check availability for this blob hash
--search_timeout=<search_timeout> : (int) how long to search for peers for the blob
in the dht
--blob_timeout=<blob_timeout> : (int) how long to try downloading from a peer
Returns:
(dict) {
"is_available": <bool, true if blob is available from a peer from peer list>
"reachable_peers": ["<ip>:<port>"],
"unreachable_peers": ["<ip>:<port>"]
}
"""
Example 2
"""
Get DHT routing information
Usage:
routing_table_get
Options:
None
Returns:
(dict) dictionary containing routing and contact information
{
"buckets": {
<bucket index>: [
{
"address": (str) peer address,
"node_id": (str) peer node id,
"blobs": (list) blob hashes announced by peer
}
]
},
"contacts": (list) contact node ids,
"blob_hashes": (list) all of the blob hashes stored by peers in the list of buckets,
"node_id": (str) the local dht node id
}
"""