add module description

nervosnetwork · Oct 11, 2023 · 3ceb03a · 3ceb03a
1 parent b0297a3
commit 3ceb03a
Show file tree

Hide file tree

Showing 5 changed files with 124 additions and 19 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/rpc/Cargo.toml b/rpc/Cargo.toml
@@ -28,7 +28,7 @@ ckb-app-config = { path = "../util/app-config", version = "= 0.112.0-pre" }
 ckb-constant = { path = "../util/constant", version = "= 0.112.0-pre" }
 jsonrpc-core = "18.0"
 serde_json = "1.0"
-jsonrpc-utils = { version = "0.2.2", features = ["server", "macros", "axum"] }
+jsonrpc-utils = { version = "0.2.3", features = ["server", "macros", "axum"] }
 ckb-jsonrpc-types = { path = "../util/jsonrpc-types", version = "= 0.112.0-pre" }
 ckb-verification = { path = "../verification", version = "= 0.112.0-pre" }
 ckb-verification-traits = { path = "../verification/traits", version = "= 0.112.0-pre" }

diff --git a/rpc/README.md b/rpc/README.md
@@ -200,6 +200,13 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
     * [Type `UncleTemplate`](#type-uncletemplate)
 * [RPC Errors](#rpc-errors)
 ### Module Alert
+ RPC Module Alert for network alerts.
+
+ An alert is a message about critical problems to be broadcast to all nodes via the p2p network.
+
+ The alerts must be signed by 2-of-4 signatures, where the public keys are hard-coded in the source code
+ and belong to early CKB developers.
+
 #### Method `send_alert`
 * `send_alert(alert)`
     * `alert`: [`Alert`](#type-alert)
@@ -256,6 +263,29 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Chain
+ RPC Module Chain for methods related to the canonical chain.
+
+ This module queries information about the canonical chain.
+
+ ##### Canonical Chain
+
+ A canonical chain is the one with the most accumulated work. The accumulated work is
+ the sum of difficulties of all the blocks in the chain.
+
+ ##### Chain Reorganization
+
+ Chain Reorganization happens when CKB found a chain that has accumulated more work than the
+ canonical chain. The reorganization reverts the blocks in the current canonical chain if needed,
+ and switch the canonical chain to that better chain.
+
+ ##### Live Cell
+
+ A cell is live if
+
+ * it is found as an output in any transaction in the [canonical chain](#canonical-chain),
+ and
+ * it is not found as an input in any transaction in the canonical chain.
+
 #### Method `get_block`
 * `get_block(block_hash, verbosity, with_cycles)`
     * `block_hash`: [`H256`](#type-h256)
@@ -1825,6 +1855,11 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Debug
+ RPC Module Debug for internal RPC methods.
+
+ **This module is for CKB developers and will not guarantee compatibility.** The methods here
+ will be changed or removed without advanced notification.
+
 #### Method `jemalloc_profiling_dump`
 * `jemalloc_profiling_dump()`
 
@@ -1859,6 +1894,12 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  Removes the logger when this is null.
 
 ### Module Experiment
+ RPC Module Experiment for experimenting methods.
+
+ **EXPERIMENTAL warning**
+
+ The methods here may be removed or changed in future releases without prior notifications.
+
 #### Method `dry_run_transaction`
 * `dry_run_transaction(tx)`
     * `tx`: [`Transaction`](#type-transaction)
@@ -2002,6 +2043,8 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Indexer
+ RPC Module Indexer.
+
 #### Method `get_indexer_tip`
 * `get_indexer_tip()`
 
@@ -2860,6 +2903,8 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Integration_test
+ RPC for Integration Test.
+
 #### Method `process_block_without_verify`
 * `process_block_without_verify(data, broadcast)`
     * `data`: [`Block`](#type-block)
@@ -3350,6 +3395,11 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Miner
+ RPC Module Miner for miners.
+
+ A miner gets a template from CKB, optionally selects transactions, resolves the PoW puzzle, and
+ submits the found new block.
+
 #### Method `get_block_template`
 * `get_block_template(bytes_limit, proposals_limit, max_version)`
     * `bytes_limit`: [`Uint64`](#type-uint64) `|` `null`
@@ -3556,6 +3606,8 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Net
+ RPC Module Net for P2P network.
+
 #### Method `local_node_info`
 * `local_node_info()`
 
@@ -4090,6 +4142,8 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Pool
+ RPC Module Pool for transaction memory pool.
+
 #### Method `send_transaction`
 * `send_transaction(tx, outputs_validator)`
     * `tx`: [`Transaction`](#type-transaction)
@@ -4368,6 +4422,8 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Stats
+ RPC Module Stats for getting various statistic data.
+
 #### Method `get_blockchain_info`
 * `get_blockchain_info()`
 
@@ -4460,6 +4516,43 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1.
  ```
 
 ### Module Subscription
+ RPC Module Subscription that CKB node will push new messages to subscribers.
+
+ RPC subscriptions require a full duplex connection. CKB offers such connections in the form of
+ TCP (enable with rpc.tcp_listen_address configuration option) and WebSocket (enable with
+ rpc.ws_listen_address).
+
+ ############### Examples
+
+ TCP RPC subscription:
+
+ ```bash
+ telnet localhost 18114
+ > {"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["new_tip_header"]}
+ < {"jsonrpc":"2.0","result":"0x0","id":2}
+ < {"jsonrpc":"2.0","method":"subscribe","params":{"result":"...block header json...",
+"subscription":0}}
+ < {"jsonrpc":"2.0","method":"subscribe","params":{"result":"...block header json...",
+"subscription":0}}
+ < ...
+ > {"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]}
+ < {"jsonrpc":"2.0","result":true,"id":2}
+ ```
+
+ WebSocket RPC subscription:
+
+ ```javascript
+ let socket = new WebSocket("ws://localhost:28114")
+
+ socket.onmessage = function(event) {
+   console.log(`Data received from server: ${event.data}`);
+ }
+
+ socket.send(`{"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["new_tip_header"]}`)
+
+ socket.send(`{"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]}`)
+ ```
+
 
 RPC Module Subscription that CKB node will push new messages to subscribers.
 

diff --git a/rpc/src/gen_doc/gen.rs b/rpc/src/gen_doc/gen.rs
@@ -5,11 +5,12 @@ use std::fs;
 
 struct RpcModule {
     pub module_title: String,
+    pub module_description: String,
     pub module_methods: Vec<serde_json::Value>,
 }
 
 impl RpcModule {
-    pub fn gen_methods_menu(&self) -> String {
+    pub fn gen_module_menu(&self) -> String {
         let mut res = String::new();
         let capitlized = capitlize(self.module_title.as_str());
         res.push_str(&format!(
@@ -34,10 +35,13 @@ impl RpcModule {
         res
     }
 
-    pub fn gen_methods_content(&self) -> String {
+    pub fn gen_module_content(&self) -> String {
         let mut res = String::new();
         let capitlized = capitlize(self.module_title.as_str());
+        let description = self.module_description.replace("##", "#####");
+
         res.push_str(&format!("### Module {}\n", capitlized));
+        res.push_str(&format!("{}\n\n", description));
 
         for method in &self.module_methods {
             // generate method signatures
@@ -87,14 +91,21 @@ impl RpcDocGenerator {
         let mut all_types: Vec<&Map<String, Value>> = vec![];
         for rpc in all_rpc {
             if let serde_json::Value::Object(map) = rpc {
-                let module_title = map["info"]["title"].as_str().unwrap();
-                // strip `_rpc` suffix
-                let module_title = &module_title[..module_title.len() - 4];
+                let module_title = map["info"]["title"]
+                    .as_str()
+                    .unwrap()
+                    .trim_end_matches("_rpc")
+                    .to_string();
+                let module_description = map["info"]["description"]
+                    .as_str()
+                    .unwrap_or_default()
+                    .to_string();
                 let module_methods = map["methods"].as_array().unwrap();
                 let types = map["components"]["schemas"].as_object().unwrap();
                 all_types.push(types);
                 rpc_module_methods.push(RpcModule {
-                    module_title: module_title.to_owned(),
+                    module_title,
+                    module_description,
                     module_methods: module_methods.to_owned(),
                 });
             }
@@ -136,7 +147,7 @@ impl RpcDocGenerator {
         // generate methods menu
         res.push_str("\n\n* [RPC Methods](#rpc-methods)\n");
         for rpc_module in self.rpc_module_methods.iter() {
-            res.push_str(&rpc_module.gen_methods_menu());
+            res.push_str(&rpc_module.gen_module_menu());
         }
 
         // generate type menu
@@ -154,12 +165,11 @@ impl RpcDocGenerator {
 
         // generate module methods content
         for rpc_module in self.rpc_module_methods.iter() {
-            let content = format!("{}\n", rpc_module.gen_methods_content());
+            let content = format!("{}\n", rpc_module.gen_module_content());
             res.push_str(&content);
         }
 
-        // generate subscription module, which is handled specially here
-        // since jsonrpc-utils ignore the `SubscriptionRpc`
+        // generate subscription module
         gen_subscription_rpc_doc(&mut res);
 
         // generate type content
@@ -278,7 +288,7 @@ fn gen_type(ty: &Value) -> String {
                         .map(|t| format!("`{}`", gen_type(t)))
                         .collect::<Vec<_>>()
                         .join(" `|` ");
-                    format!("{}", ty)
+                    ty.to_string()
                 } else {
                     format!("`{}`", ty.as_str().unwrap())
                 }
@@ -320,6 +330,8 @@ fn gen_errors_content(res: &mut String) {
     }
 }
 
+/// generate subscription module, which is handled specially here
+/// since jsonrpc-utils ignore the `SubscriptionRpc`
 fn gen_subscription_rpc_doc(res: &mut String) {
     let pubsub_module_source = include_str!("../module/subscription.rs");
     // read comments before `pub trait SubscriptionRpc` and treat it as module summary
@@ -330,7 +342,7 @@ fn gen_subscription_rpc_doc(res: &mut String) {
         .map(|l| {
             l.trim_start()
                 .trim_start_matches("///")
-                .replacen(" ", "", 1)
+                .replacen(' ', "", 1)
         })
         .collect::<Vec<_>>()
         .join("\n");
@@ -343,7 +355,7 @@ fn gen_subscription_rpc_doc(res: &mut String) {
         .map(|l| {
             l.trim_start()
                 .trim_start_matches("///")
-                .replacen(" ", "", 1)
+                .replacen(' ', "", 1)
         })
         .collect::<Vec<_>>()
         .join("\n");

diff --git a/rpc/src/module/debug.rs b/rpc/src/module/debug.rs
@@ -4,11 +4,11 @@ use ckb_logger_service::Logger;
 use jsonrpc_core::{Error, ErrorCode::InternalError, Result};
 use jsonrpc_utils::rpc;
 use std::time;
+
 /// RPC Module Debug for internal RPC methods.
 ///
 /// **This module is for CKB developers and will not guarantee compatibility.** The methods here
 /// will be changed or removed without advanced notification.
-#[doc(hidden)]
 #[rpc(openrpc)]
 #[async_trait]
 pub trait DebugRpc {