Documentation updates (kaspanet#570)

* docs

* Export ConsensusSessionOwned

* add CI pass to run `cargo doc`

* module rust docs

* lints

* fix typos

* replace glob import terminology with "re-exports"

* cleanup

.github/workflows/ci.yaml

@@ -126,6 +126,9 @@ jobs:
       - name: Run cargo doc tests with features=no-asm on kaspa-hashes
         run: cargo test --doc --release -p kaspa-hashes --features=no-asm
 
+      - name: Run cargo doc
+        run: cargo doc --release --no-deps --workspace
+
   # test-release:
   #   name: Test Suite Release
   #   runs-on: ${{ matrix.os }}

cli/src/modules/connect.rs

@@ -14,11 +14,11 @@ impl Connect {
             let (is_public, url) = match arg_or_server_address.as_deref() {
                 Some("public") => {
                     tprintln!(ctx, "Connecting to a public node");
-                    (true, Resolver::default().fetch(WrpcEncoding::Borsh, network_id).await.map_err(|e| e.to_string())?.url)
+                    (true, Resolver::default().get_url(WrpcEncoding::Borsh, network_id).await.map_err(|e| e.to_string())?)
                 }
                 None => {
                     tprintln!(ctx, "No server set, connecting to a public node");
-                    (true, Resolver::default().fetch(WrpcEncoding::Borsh, network_id).await.map_err(|e| e.to_string())?.url)
+                    (true, Resolver::default().get_url(WrpcEncoding::Borsh, network_id).await.map_err(|e| e.to_string())?)
                 }
                 Some(url) => {
                     (false, wrpc_client.parse_url_with_network_type(url.to_string(), network_id.into()).map_err(|e| e.to_string())?)

components/consensusmanager/src/lib.rs

@@ -9,7 +9,8 @@ mod session;
 
 pub use batch::BlockProcessingBatch;
 pub use session::{
-    spawn_blocking, ConsensusInstance, ConsensusProxy, ConsensusSessionBlocking, SessionLock, SessionReadGuard, SessionWriteGuard,
+    spawn_blocking, ConsensusInstance, ConsensusProxy, ConsensusSessionBlocking, ConsensusSessionOwned, SessionLock, SessionReadGuard,
+    SessionWriteGuard,
 };
 
 /// Consensus controller trait. Includes methods required to start/stop/control consensus, but which should not

components/consensusmanager/src/session.rs

@@ -91,7 +91,7 @@ impl ConsensusInstance {
 
     /// Returns an unguarded *blocking* consensus session. There's no guarantee that data will not be pruned between
     /// two sequential consensus calls. This session doesn't hold the consensus pruning lock, so it should
-    /// be preferred upon [`session_blocking`] when data consistency is not important.
+    /// be preferred upon [`session_blocking()`](Self::session_blocking) when data consistency is not important.
     pub fn unguarded_session_blocking(&self) -> ConsensusSessionBlocking<'static> {
         ConsensusSessionBlocking::new_without_session_guard(self.consensus.clone())
     }
@@ -100,7 +100,7 @@ impl ConsensusInstance {
     /// that consensus state is consistent between operations, that is, no pruning was performed between the calls.
     /// The returned object is an *owned* consensus session type which can be cloned and shared across threads.
     /// The sharing ability is useful for spawning blocking operations on a different thread using the same
-    /// session object, see [`ConsensusSessionOwned::spawn_blocking`]. The caller is responsible to make sure
+    /// session object, see [`ConsensusSessionOwned::spawn_blocking()`](ConsensusSessionOwned::spawn_blocking). The caller is responsible to make sure
     /// that the overall lifetime of this session is not too long (~2 seconds max)
     pub async fn session(&self) -> ConsensusSessionOwned {
         let g = self.session_lock.read_owned().await;
@@ -109,7 +109,7 @@ impl ConsensusInstance {
 
     /// Returns an unguarded consensus session. There's no guarantee that data will not be pruned between
     /// two sequential consensus calls. This session doesn't hold the consensus pruning lock, so it should
-    /// be preferred upon [`session`] when data consistency is not important.
+    /// be preferred upon [`session()`](Self::session) when data consistency is not important.
     pub fn unguarded_session(&self) -> ConsensusSessionOwned {
         ConsensusSessionOwned::new_without_session_guard(self.consensus.clone())
     }
@@ -139,7 +139,8 @@ impl Deref for ConsensusSessionBlocking<'_> {
 }
 
 /// An *owned* consensus session type which can be cloned and shared across threads.
-/// See method `spawn_blocking` within for context on the usefulness of this type
+/// See method `spawn_blocking` within for context on the usefulness of this type.
+/// Please note - you must use [`ConsensusProxy`] type alias instead of this struct.
 #[derive(Clone)]
 pub struct ConsensusSessionOwned {
     _session_guard: Option<SessionOwnedReadGuard>,

consensus/client/src/error.rs

@@ -1,3 +1,5 @@
+//! The [`Error`](enum@Error) enum used by this crate
+
 use thiserror::Error;
 use wasm_bindgen::{JsError, JsValue};
 use workflow_wasm::jserror::JsErrorData;

consensus/client/src/hash.rs

@@ -1,3 +1,10 @@
+//!
+//! WASM bindings for transaction hashers: [`TransactionSigningHash`](native::TransactionSigningHash)
+//! and [`TransactionSigningHashECDSA`](native::TransactionSigningHashECDSA).
+//!
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 use crate::result::Result;
 use kaspa_hashes as native;

consensus/client/src/header.rs

@@ -1,3 +1,9 @@
+//!
+//! Implementation of the Block [`Header`] struct.
+//!
+
+#![allow(non_snake_case)]
+
 use crate::error::Error;
 use js_sys::{Array, Object};
 use kaspa_consensus_core::hashing;
@@ -59,10 +65,15 @@ export interface IRawHeader {
 
 #[wasm_bindgen]
 extern "C" {
+    /// WASM (TypeScript) type definition for the Header-like struct: `Header | IHeader | IRawHeader`.
+    ///
+    /// @category Consensus
     #[wasm_bindgen(typescript_type = "Header | IHeader | IRawHeader")]
     pub type HeaderT;
 }
 
+/// Kaspa Block Header
+///
 /// @category Consensus
 #[derive(Clone, Debug, Serialize, Deserialize, CastFromJs)]
 #[serde(rename_all = "camelCase")]

consensus/client/src/input.rs

@@ -1,3 +1,9 @@
+//!
+//! Implementation of the client-side [`TransactionInput`] struct used by the client-side [`Transaction`] struct.
+//!
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 use crate::result::Result;
 use crate::TransactionOutpoint;
@@ -33,14 +39,21 @@ export interface ITransactionInputVerboseData { }
 
 #[wasm_bindgen]
 extern "C" {
+    /// WASM (TypeScript) type representing `ITransactionInput | TransactionInput`
+    /// @category Consensus
     #[wasm_bindgen(typescript_type = "ITransactionInput | TransactionInput")]
     pub type TransactionInputT;
+    /// WASM (TypeScript) type representing `ITransactionInput[] | TransactionInput[]`
+    /// @category Consensus
     #[wasm_bindgen(typescript_type = "(ITransactionInput | TransactionInput)[]")]
     pub type TransactionInputArrayAsArgT;
+    /// WASM (TypeScript) type representing `TransactionInput[]`
+    /// @category Consensus
     #[wasm_bindgen(typescript_type = "TransactionInput[]")]
     pub type TransactionInputArrayAsResultT;
 }
 
+/// Inner type used by [`TransactionInput`]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionInputInner {

consensus/client/src/lib.rs

@@ -1,3 +1,17 @@
+//!
+//! # Client-side consensus primitives.
+//!
+//! This crate offers client-side primitives mirroring the consensus layer of the Kaspa p2p node.
+//! It declares structs such as [`Transaction`], [`TransactionInput`], [`TransactionOutput`],
+//! [`TransactionOutpoint`], [`UtxoEntry`], and [`UtxoEntryReference`]
+//! that are used by the Wallet subsystem as well as WASM bindings.
+//!
+//! Unlike raw consensus primitives (used for high-performance DAG processing) the primitives
+//! offered in this crate are designed to be used in client-side applications. Their internal
+//! data is typically wrapped into `Arc<Mutex<T>>`, allowing for easy sharing between
+//! async / threaded environments and WASM bindings.
+//!
+
 pub mod error;
 mod imports;
 mod input;

consensus/client/src/outpoint.rs

@@ -1,3 +1,11 @@
+//!
+//! Implementation of the client-side [`TransactionOutpoint`] used by the [`TransactionInput`] struct.
+//!
+
+#![allow(non_snake_case)]
+
+use cfg_if::cfg_if;
+
 use crate::imports::*;
 use crate::result::Result;
 
@@ -14,6 +22,7 @@ export interface ITransactionOutpoint {
 }
 "#;
 
+/// Inner type used by [`TransactionOutpoint`]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Ord, PartialOrd)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionOutpointInner {
@@ -110,26 +119,31 @@ impl TransactionOutpoint {
     }
 }
 
-#[cfg_attr(feature = "wasm32-sdk", wasm_bindgen)]
-impl TransactionOutpoint {
-    #[cfg_attr(feature = "wasm32-sdk", wasm_bindgen(constructor))]
-    pub fn ctor(transaction_id: TransactionId, index: u32) -> TransactionOutpoint {
-        Self { inner: Arc::new(TransactionOutpointInner { transaction_id, index }) }
-    }
+cfg_if! {
+    if #[cfg(feature = "wasm32-sdk")] {
 
-    #[cfg_attr(feature = "wasm32-sdk", wasm_bindgen(js_name = "getId"))]
-    pub fn id_string(&self) -> String {
-        format!("{}-{}", self.get_transaction_id_as_string(), self.get_index())
-    }
+        #[wasm_bindgen]
+        impl TransactionOutpoint {
+            #[wasm_bindgen(constructor)]
+            pub fn ctor(transaction_id: TransactionId, index: u32) -> TransactionOutpoint {
+                Self { inner: Arc::new(TransactionOutpointInner { transaction_id, index }) }
+            }
 
-    #[cfg_attr(feature = "wasm32-sdk", wasm_bindgen(getter, js_name = transactionId))]
-    pub fn get_transaction_id_as_string(&self) -> String {
-        self.inner().transaction_id.to_string()
-    }
+            #[wasm_bindgen(js_name = "getId")]
+            pub fn id_string(&self) -> String {
+                format!("{}-{}", self.get_transaction_id_as_string(), self.get_index())
+            }
 
-    #[cfg_attr(feature = "wasm32-sdk", wasm_bindgen(getter, js_name = index))]
-    pub fn get_index(&self) -> TransactionIndexType {
-        self.inner().index
+            #[wasm_bindgen(getter, js_name = transactionId)]
+            pub fn get_transaction_id_as_string(&self) -> String {
+                self.inner().transaction_id.to_string()
+            }
+
+            #[wasm_bindgen(getter, js_name = index)]
+            pub fn get_index(&self) -> TransactionIndexType {
+                self.inner().index
+            }
+        }
     }
 }
 

consensus/client/src/output.rs

@@ -1,3 +1,9 @@
+//!
+//! Implementation of the client-side [`TransactionOutput`] used by the [`Transaction`] struct.
+//!
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 
 #[wasm_bindgen(typescript_custom_section)]
@@ -28,14 +34,21 @@ export interface ITransactionOutputVerboseData {
 
 #[wasm_bindgen]
 extern "C" {
+    /// WASM (TypeScript) type representing `ITransactionOutput | TransactionOutput`
+    /// @category Consensus
     #[wasm_bindgen(typescript_type = "ITransactionOutput | TransactionOutput")]
     pub type TransactionOutputT;
+    /// WASM (TypeScript) type representing `ITransactionOutput[] | TransactionOutput[]`
+    /// @category Consensus
     #[wasm_bindgen(typescript_type = "(ITransactionOutput | TransactionOutput)[]")]
     pub type TransactionOutputArrayAsArgT;
+    /// WASM (TypeScript) type representing `TransactionOutput[]`
+    /// @category Consensus
     #[wasm_bindgen(typescript_type = "TransactionOutput[]")]
     pub type TransactionOutputArrayAsResultT;
 }
 
+/// Inner type used by [`TransactionOutput`]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionOutputInner {

consensus/client/src/result.rs

@@ -1 +1,3 @@
+//! [`Result`] type alias that is bound to the [`Error`](super::error::Error) type from this crate.
+
 pub type Result<T, E = super::error::Error> = std::result::Result<T, E>;

consensus/client/src/serializable/mod.rs

@@ -1,3 +1,24 @@
+//!
+//! # Standardized JSON serialization and deserialization of Kaspa transactions.
+//!
+//! This module provides standardized JSON serialization and deserialization of
+//! Kaspa transactions. There are two sub-modules: `numeric` and `string`.
+//!
+//! The `numeric` module provides serialization and deserialization of transactions
+//! with all large integer values as `bigint` types in WASM or numerical values that
+//! exceed the largest integer that can be represented by the JavaScript `number` type.
+//!
+//! The `string` module provides serialization and deserialization of transactions
+//! with all large integer values as `string` types. This allows deserialization
+//! via JSON in JavaScript environments and later conversion to `bigint` types.
+//!
+//! These data structures can be used for manual transport of transactions using JSON.
+//! For more advanced use cases, please refer to `PSKT` in the [`kaspa_wallet_pskt`](https://docs.rs/kaspa_wallet_pskt)
+//! crate.
+//!
+
+#![allow(non_snake_case)]
+
 pub mod numeric;
 pub mod string;
 
@@ -80,6 +101,7 @@ export interface ISerializableTransaction {
 
 #[wasm_bindgen]
 extern "C" {
+    /// WASM (TypeScript) representation of the `ISerializableTransaction` interface.
     #[wasm_bindgen(extends = js_sys::Array, typescript_type = "ISerializableTransaction")]
     pub type SerializableTransactionT;
 }

consensus/client/src/serializable/numeric.rs

@@ -1,4 +1,10 @@
-//! This module implements the primitives for external transaction signing.
+//!
+//! This module implements transaction-related primitives for JSON serialization
+//! where all large integer values (`u64`) are serialized to JSON using `serde` and
+//! can exceed the largest integer value representable by the JavaScript `number` type.
+//! (i.e. transactions serialized using this module can not be deserialized in JavaScript
+//! but may be deserialized in other JSON-capable environments that support large integers)
+//!
 
 use crate::error::Error;
 use crate::imports::*;

consensus/client/src/serializable/string.rs

@@ -1,4 +1,7 @@
-//! This module implements the primitives for external transaction signing.
+//!
+//! This module implements transaction-related primitives for JSON serialization
+//! where all large integer values (`u64`) are serialized to and from JSON as strings.
+//!
 
 use crate::imports::*;
 use crate::result::Result;

consensus/client/src/sign.rs

@@ -1,3 +1,7 @@
+//!
+//! Utilities for signing transactions.
+//!
+
 use crate::transaction::Transaction;
 use core::iter::once;
 use itertools::Itertools;

consensus/client/src/transaction.rs

@@ -1,3 +1,7 @@
+//!
+//! Declares the client-side [`Transaction`] type, which represents a Kaspa transaction.
+//!
+
 #![allow(non_snake_case)]
 
 use crate::imports::*;
@@ -53,10 +57,13 @@ export interface ITransactionVerboseData {
 
 #[wasm_bindgen]
 extern "C" {
+    /// WASM (TypeScript) type representing `ITransaction | Transaction`
+    /// @category Consensus
     #[wasm_bindgen(typescript_type = "ITransaction | Transaction")]
     pub type TransactionT;
 }
 
+/// Inner type used by [`Transaction`]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionInner {

consensus/client/src/utils.rs

@@ -1,3 +1,9 @@
+//!
+//! Client-side utility functions and their WASM bindings.
+//!
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 use crate::result::Result;
 use kaspa_addresses::*;