Skip to content
This repository has been archived by the owner on Sep 14, 2023. It is now read-only.

Commit

Permalink
convert rust doc comments to jsdoc
Browse files Browse the repository at this point in the history 
([^\S\n]*)((?:\/\/\/.*\n(\s*))+)
$1/**\n$1$2 */\n$3

\/\/\/
 *

\/\*\*\n\s*\* (.+)\n\s*\*\/
/** $1 */
  • Loading branch information
@tjjfvi
tjjfvi committed Oct 22, 2022
1 parent 63ee3dc commit 237b337
Show file tree
Hide file tree
Showing 15 changed files with 582 additions and 477 deletions.
20 changes: 5 additions & 15 deletions known/rpc.ts
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,15 @@
import * as rpc from "../rpc/mod.ts";

export type ErrorDetails = rpc.EnsureErrorDetails<{
/**
* Invalid JSON was received by the server.
*/
/** Invalid JSON was received by the server. */
ParseError: [-32700];
/**
* The JSON sent is not a valid Request object.
*/
/** The JSON sent is not a valid Request object. */
InvalidRequest: [-32600];
/**
* The method does not exist / is not available.
*/
/** The method does not exist / is not available. */
MethodNotFound: [-32601];
/**
* Invalid method parameter(s).
*/
/** Invalid method parameter(s). */
InvalidParams: [-32602];
/**
* Internal JSON-RPC error.
*/
/** Internal JSON-RPC error. */
InternalError: [-32603];
/**
* Other internal server error.
Expand Down
144 changes: 77 additions & 67 deletions known/rpc/author.ts
View file
Original file line number Diff line number Diff line change
@@ -1,84 +1,92 @@
import { Hash, Hex, Result, SerdeEnum, Subscription } from "./utils.ts";

// https://github.com/paritytech/substrate/blob/e0ccd00/client/transaction-pool/api/src/lib.rs#L104
/// Possible transaction status events.
///
/// This events are being emitted by `TransactionPool` watchers,
/// which are also exposed over RPC.
///
/// The status events can be grouped based on their kinds as:
/// 1. Entering/Moving within the pool:
/// - `Future`
/// - `Ready`
/// 2. Inside `Ready` queue:
/// - `Broadcast`
/// 3. Leaving the pool:
/// - `InBlock`
/// - `Invalid`
/// - `Usurped`
/// - `Dropped`
/// 4. Re-entering the pool:
/// - `Retracted`
/// 5. Block finalized:
/// - `Finalized`
/// - `FinalityTimeout`
///
/// The events will always be received in the order described above, however
/// there might be cases where transactions alternate between `Future` and `Ready`
/// pool, and are `Broadcast` in the meantime.
///
/// There is also only single event causing the transaction to leave the pool.
/// I.e. only one of the listed ones should be triggered.
///
/// Note that there are conditions that may cause transactions to reappear in the pool.
/// 1. Due to possible forks, the transaction that ends up being in included
/// in one block, may later re-enter the pool or be marked as invalid.
/// 2. Transaction `Dropped` at one point, may later re-enter the pool if some other
/// transactions are removed.
/// 3. `Invalid` transaction may become valid at some point in the future.
/// (Note that runtimes are encouraged to use `UnknownValidity` to inform the pool about
/// such case).
/// 4. `Retracted` transactions might be included in some next block.
///
/// The stream is considered finished only when either `Finalized` or `FinalityTimeout`
/// event is triggered. You are however free to unsubscribe from notifications at any point.
/// The first one will be emitted when the block, in which transaction was included gets
/// finalized. The `FinalityTimeout` event will be emitted when the block did not reach finality
/// within 512 blocks. This either indicates that finality is not available for your chain,
/// or that finality gadget is lagging behind. If you choose to wait for finality longer, you can
/// re-subscribe for a particular transaction hash manually again.
/**
* Possible transaction status events.
*
* This events are being emitted by `TransactionPool` watchers,
* which are also exposed over RPC.
*
* The status events can be grouped based on their kinds as:
* 1. Entering/Moving within the pool:
* - `Future`
* - `Ready`
* 2. Inside `Ready` queue:
* - `Broadcast`
* 3. Leaving the pool:
* - `InBlock`
* - `Invalid`
* - `Usurped`
* - `Dropped`
* 4. Re-entering the pool:
* - `Retracted`
* 5. Block finalized:
* - `Finalized`
* - `FinalityTimeout`
*
* The events will always be received in the order described above, however
* there might be cases where transactions alternate between `Future` and `Ready`
* pool, and are `Broadcast` in the meantime.
*
* There is also only single event causing the transaction to leave the pool.
* I.e. only one of the listed ones should be triggered.
*
* Note that there are conditions that may cause transactions to reappear in the pool.
* 1. Due to possible forks, the transaction that ends up being in included
* in one block, may later re-enter the pool or be marked as invalid.
* 2. Transaction `Dropped` at one point, may later re-enter the pool if some other
* transactions are removed.
* 3. `Invalid` transaction may become valid at some point in the future.
* (Note that runtimes are encouraged to use `UnknownValidity` to inform the pool about
* such case).
* 4. `Retracted` transactions might be included in some next block.
*
* The stream is considered finished only when either `Finalized` or `FinalityTimeout`
* event is triggered. You are however free to unsubscribe from notifications at any point.
* The first one will be emitted when the block, in which transaction was included gets
* finalized. The `FinalityTimeout` event will be emitted when the block did not reach finality
* within 512 blocks. This either indicates that finality is not available for your chain,
* or that finality gadget is lagging behind. If you choose to wait for finality longer, you can
* re-subscribe for a particular transaction hash manually again.
*/
export type TransactionStatus = SerdeEnum<{
/// Transaction is part of the future queue.
/** Transaction is part of the future queue. */
future: void;
/// Transaction is part of the ready queue.
/** Transaction is part of the ready queue. */
ready: void;
/// The transaction has been broadcast to the given peers.
/** The transaction has been broadcast to the given peers. */
broadcast: string[];
/// Transaction has been included in block with given hash.
/** Transaction has been included in block with given hash. */
inBlock: Hash;
/// The block this transaction was included in has been retracted.
/** The block this transaction was included in has been retracted. */
retracted: Hash;
/// Maximum number of finality watchers has been reached,
/// old watchers are being removed.
/**
* Maximum number of finality watchers has been reached,
* old watchers are being removed.
*/
finalityTimeout: Hash;
/// Transaction has been finalized by a finality-gadget, e.g GRANDPA
/** Transaction has been finalized by a finality-gadget, e.g GRANDPA */
finalized: Hash;
/// Transaction has been replaced in the pool, by another transaction
/// that provides the same tags. (e.g. same (sender, nonce)).
/**
* Transaction has been replaced in the pool, by another transaction
* that provides the same tags. (e.g. same (sender, nonce)).
*/
usurped: Hash;
/// Transaction has been dropped from the pool because of the limit.
/** Transaction has been dropped from the pool because of the limit. */
dropped: void;
/// Transaction is no longer valid in the current state.
/** Transaction is no longer valid in the current state. */
invalid: void;
}>;

/// RPC Extrinsic or hash
///
/// Allows to refer to extrinsic either by its raw representation or its hash.
/**
* RPC Extrinsic or hash
*
* Allows to refer to extrinsic either by its raw representation or its hash.
*/
export type ExtrinsicOrHash = SerdeEnum<{
/// The hash of the extrinsic.
/** The hash of the extrinsic. */
hash: Hash;
/// Raw extrinsic bytes.
/** Raw extrinsic bytes. */
extrinsic: Hex;
}>;

Expand All @@ -105,10 +113,12 @@ export type AuthorRpc = {
author_pendingExtrinsics(): Result<Hex[]>;
/** Remove given extrinsic from the pool and temporarily ban it to prevent reimporting. */
author_removeExtrinsic(extrinsics: ExtrinsicOrHash[]): Result<Hex[]>; // todo
/// Submit an extrinsic to watch.
///
/// See [`TransactionStatus`](sc_transaction_pool_api::TransactionStatus) for details on
/// transaction life cycle.
/**
* Submit an extrinsic to watch.
*
* See [`TransactionStatus`](sc_transaction_pool_api::TransactionStatus) for details on
* transaction life cycle.
*/
author_submitAndWatchExtrinsic(
extrinsic: Hex,
): Result<Subscription<"author_submitAndWatchExtrinsic", TransactionStatus>>;
Expand Down
8 changes: 4 additions & 4 deletions known/rpc/babe.ts
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
import { AccountId, Result } from "./utils.ts";

// https://github.com/paritytech/substrate/blob/9b01569/client/consensus/babe/rpc/src/lib.rs#L154
/// Holds information about the `slot`'s that can be claimed by a given key.
/** Holds information about the `slot`'s that can be claimed by a given key. */
export interface EpochAuthorship {
/// the array of primary slots that can be claimed
/** the array of primary slots that can be claimed */
primary: number[];
/// the array of secondary slots that can be claimed
/** the array of secondary slots that can be claimed */
secondary: number[];
/// The array of secondary VRF slots that can be claimed.
/** The array of secondary VRF slots that can be claimed. */
secondary_vrf: number[];
}

Expand Down
14 changes: 8 additions & 6 deletions known/rpc/beefy.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,16 @@ import { Hash, Hex, Result, Subscription } from "./utils.ts";

// https://github.com/paritytech/substrate/blob/317808a/client/beefy/rpc/src/lib.rs#L84
export type BeefyRpc = {
/// Returns the block most recently finalized by BEEFY, alongside side its justification.
/** Returns the block most recently finalized by BEEFY, alongside side its justification. */
beefy_subscribeJustifications(): Result<
Subscription<"beefy_subscribeJustifications", Hex>
>;
/// Returns hash of the latest BEEFY finalized block as seen by this client.
///
/// The latest BEEFY block might not be available if the BEEFY gadget is not running
/// in the network or if the client is still initializing or syncing with the network.
/// In such case an error would be returned.
/**
* Returns hash of the latest BEEFY finalized block as seen by this client.
*
* The latest BEEFY block might not be available if the BEEFY gadget is not running
* in the network or if the client is still initializing or syncing with the network.
* In such case an error would be returned.
*/
beefy_getFinalizedHead(): Result<Hash>;
};
42 changes: 22 additions & 20 deletions known/rpc/chain.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,41 @@ import { HexEncoded } from "../../util/branded.ts";
import { Hash, Hex, ListOrValue, NumberOrHex, Result, Subscription } from "./utils.ts";

// https://github.com/paritytech/substrate/blob/0ba251c/primitives/runtime/src/generic/digest.rs
/// Generic header digest.
/** Generic header digest. */
export interface Digest {
/// A list of logs in the digest.
/** A list of logs in the digest. */
logs: Hex[];
}

// https://github.com/paritytech/substrate/blob/01a3ad65/primitives/runtime/src/generic/header.rs#L39
/// Abstraction over a block header for a substrate chain.
/** Abstraction over a block header for a substrate chain. */
export interface Header {
/// The parent hash.
/** The parent hash. */
parentHash: Hash;
/// The block number.
/** The block number. */
number: HexEncoded<bigint>;
/// The state trie merkle root
/** The state trie merkle root */
stateRoot: Hash;
/// The merkle root of the extrinsics.
/** The merkle root of the extrinsics. */
extrinsicsRoot: Hash;
/// A chain-specific digest of data useful for light clients or referencing auxiliary data.
/** A chain-specific digest of data useful for light clients or referencing auxiliary data. */
digest: Digest;
}

// https://github.com/paritytech/substrate/blob/ded44948/primitives/runtime/src/generic/block.rs#L126
/// Abstraction over a substrate block and justification.
/** Abstraction over a substrate block and justification. */
export interface SignedBlock {
/// Full block.
/** Full block. */
block: Block;
/// Block justification.
/** Block justification. */
justifications?: [number[], number[]][];
}

// https://github.com/paritytech/substrate/blob/ded44948/primitives/runtime/src/generic/block.rs#L88
export interface Block {
/// The block header.
/** The block header. */
header: Header;
/// The accompanying extrinsics.
/** The accompanying extrinsics. */
extrinsics: Hex[];
}

Expand All @@ -46,25 +46,27 @@ export type ChainRpc = {
chain_getHeader(hash?: Hash): Result<Header | null>;
/** Get header and body of a relay chain block. */
chain_getBlock(hash?: Hash): Result<SignedBlock | null>;
/// Get hash of the n-th block in the canon chain.
///
/// By default returns latest block hash.
/**
* Get hash of the n-th block in the canon chain.
*
* By default returns latest block hash.
*/
chain_getBlockHash(height?: ListOrValue<NumberOrHex>): Result<ListOrValue<Hash | null>>;
chain_getHead: ChainRpc["chain_getBlockHash"];
/// Get hash of the last finalized block in the canon chain.
/** Get hash of the last finalized block in the canon chain. */
chain_getFinalizedHead(): Result<Hash>;
chain_getFinalisedHead: ChainRpc["chain_getFinalizedHead"];
/// All head subscription.
/** All head subscription. */
chain_subscribeAllHeads(): Result<Subscription<"chain_subscribeAllHeads", Header>>;
chain_unsubscribeAllHeads(
subscription: Subscription<"chain_subscribeAllHeads", Header>,
): Result<void>;
/// New head subscription.
/** New head subscription. */
chain_subscribeNewHeads(): Result<Subscription<"chain_subscribeAllHeads", Header>>;
chain_unsubscribeNewHeads(
subscription: Subscription<"chain_subscribeAllHeads", Header>,
): Result<void>;
/// Finalized head subscription.
/** Finalized head subscription. */
chain_subscribeFinalizedHeads(): Result<Subscription<"chain_subscribeAllHeads", Header>>;
chain_unsubscribeFinalizedHeads(
subscription: Subscription<"chain_subscribeAllHeads", Header>,
Expand Down
22 changes: 12 additions & 10 deletions known/rpc/childstate.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ export type StorageData = Hex;

// https://github.com/paritytech/substrate/blob/ded44948/client/rpc-api/src/state/helpers.rs#L27
export interface ReadProof {
/// Block hash used to generate the proof
/** Block hash used to generate the proof */
at: Hash;
/// A proof used to prove that storage entries are included in the storage trie
/** A proof used to prove that storage entries are included in the storage trie */
proof: Hex[];
}

Expand All @@ -24,41 +24,43 @@ export type ChildStateRpc = {
prefix: StorageKey,
hash?: Hash,
): Result<StorageKey[]>;
/// Returns the keys with prefix from a child storage with pagination support.
/// Up to `count` keys will be returned.
/// If `start_key` is passed, return next keys in storage in lexicographic order.
/**
* Returns the keys with prefix from a child storage with pagination support.
* Up to `count` keys will be returned.
* If `start_key` is passed, return next keys in storage in lexicographic order.
*/
childState_getKeysPaged(
childStorageKey: PrefixedStorageKey,
prefix: StorageKey,
count: number,
startKey?: StorageKey,
hash?: Hash,
): Result<StorageKey[]>;
/// Returns a child storage entry at a specific block's state.
/** Returns a child storage entry at a specific block's state. */
childState_getStorage(
childStorageKey: PrefixedStorageKey,
key: StorageKey,
hash?: Hash,
): Result<StorageData | null>;
/// Returns child storage entries for multiple keys at a specific block's state.
/** Returns child storage entries for multiple keys at a specific block's state. */
childState_getStorageEntries(
childStorageKey: PrefixedStorageKey,
keys: StorageKey[],
hash?: Hash,
): Result<(StorageData | null)[]>;
/// Returns the hash of a child storage entry at a block's state.
/** Returns the hash of a child storage entry at a block's state. */
childState_getStorageHash(
childStorageKey: PrefixedStorageKey,
key: StorageKey,
hash?: Hash,
): Result<Hash | null>;
/// Returns the size of a child storage entry at a block's state.
/** Returns the size of a child storage entry at a block's state. */
childState_getStorageSize(
childStorageKey: PrefixedStorageKey,
key: StorageKey,
hash?: Hash,
): Result<number | null>;
/// Returns proof of storage for child key entries at a specific block's state.
/** Returns proof of storage for child key entries at a specific block's state. */
state_getChildReadProof(
childStorageKey: PrefixedStorageKey,
keys: StorageKey[],
Expand Down
Loading

0 comments on commit 237b337

Please sign in to comment.