From 37ee0b5599557258771ea8666a59f7039116c2bd Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Thu, 15 Jul 2021 19:40:07 -0500 Subject: [PATCH] Eliminate doc warnings and fix some markdown (#18566) * Fix link target in doc comment * Fix formatting of log examples in process_instruction * Fix doc markdown in solana-gossip * Fix doc markdown in solana-runtime * Escape square braces in doc comments to avoid warnings * Surround 'account references' doc items in code spans to avoid warnings * Fix code block in loader_upgradeable_instruction * Fix doctest for loader_upgradable_instruction --- gossip/src/crds_gossip.rs | 27 +++-- gossip/src/crds_gossip_pull.rs | 17 +-- gossip/src/crds_gossip_push.rs | 27 +++-- ledger/src/blockstore/blockstore_purge.rs | 4 +- programs/vote/src/vote_instruction.rs | 54 ++++----- runtime/src/append_vec.rs | 7 +- runtime/src/bloom.rs | 10 +- .../src/loader_upgradeable_instruction.rs | 47 ++++---- sdk/program/src/program_option.rs | 2 +- sdk/program/src/stake/instruction.rs | 104 +++++++++--------- sdk/program/src/system_instruction.rs | 58 +++++----- sdk/src/process_instruction.rs | 21 +++- 12 files changed, 208 insertions(+), 170 deletions(-) diff --git a/gossip/src/crds_gossip.rs b/gossip/src/crds_gossip.rs index 8a7b20a84..034b6a57a 100644 --- a/gossip/src/crds_gossip.rs +++ b/gossip/src/crds_gossip.rs @@ -1,4 +1,5 @@ -//! Crds Gossip +//! Crds Gossip. +//! //! This module ties together Crds and the push and pull gossip overlays. The interface is //! designed to run with a simulator or over a UDP network connection with messages up to a //! packet::PACKET_DATA_SIZE size. @@ -39,7 +40,8 @@ pub struct CrdsGossip { } impl CrdsGossip { - /// process a push message to the network + /// Process a push message to the network. + /// /// Returns unique origins' pubkeys of upserted values. pub fn process_push_message( &self, @@ -54,7 +56,7 @@ impl CrdsGossip { .collect() } - /// remove redundant paths in the network + /// Remove redundant paths in the network. pub fn prune_received_cache( &self, self_pubkey: &Pubkey, @@ -145,7 +147,7 @@ impl CrdsGossip { Ok(()) } - /// add the `from` to the peer's filter of nodes + /// Add the `from` to the peer's filter of nodes. pub fn process_prune_msg( &self, self_pubkey: &Pubkey, @@ -167,8 +169,7 @@ impl CrdsGossip { } } - /// refresh the push active set - /// * ratio - number of actives to rotate + /// Refresh the push active set. pub fn refresh_push_active_set( &self, self_pubkey: &Pubkey, @@ -188,7 +189,7 @@ impl CrdsGossip { ) } - /// generate a random request + /// Generate a random request. #[allow(clippy::too_many_arguments)] pub fn new_pull_request( &self, @@ -216,14 +217,15 @@ impl CrdsGossip { ) } - /// time when a request to `from` was initiated + /// Time when a request to `from` was initiated. + /// /// This is used for weighted random selection during `new_pull_request` /// It's important to use the local nodes request creation time as the weight /// instead of the response received time otherwise failed nodes will increase their weight. pub fn mark_pull_request_creation_time(&self, from: Pubkey, now: u64) { self.pull.mark_pull_request_creation_time(from, now) } - /// process a pull request and create a response + /// Process a pull request and create a response. pub fn process_pull_requests(&self, callers: I, now: u64) where I: IntoIterator, @@ -255,7 +257,7 @@ impl CrdsGossip { .filter_pull_responses(&self.crds, timeouts, response, now, process_pull_stats) } - /// process a pull response + /// Process a pull response. pub fn process_pull_responses( &self, from: &Pubkey, @@ -322,14 +324,15 @@ impl CrdsGossip { } } -/// Computes a normalized(log of actual stake) stake +/// Computes a normalized (log of actual stake) stake. pub fn get_stake(id: &Pubkey, stakes: &HashMap) -> f32 { // cap the max balance to u32 max (it should be plenty) let bal = f64::from(u32::max_value()).min(*stakes.get(id).unwrap_or(&0) as f64); 1_f32.max((bal as f32).ln()) } -/// Computes bounded weight given some max, a time since last selected, and a stake value +/// Computes bounded weight given some max, a time since last selected, and a stake value. +/// /// The minimum stake is 1 and not 0 to allow 'time since last' picked to factor in. pub fn get_weight(max_weight: f32, time_since_last_selected: u32, stake: f32) -> f32 { let mut weight = time_since_last_selected as f32 * stake; diff --git a/gossip/src/crds_gossip_pull.rs b/gossip/src/crds_gossip_pull.rs index 89ca3b300..fd24694f6 100644 --- a/gossip/src/crds_gossip_pull.rs +++ b/gossip/src/crds_gossip_pull.rs @@ -1,7 +1,9 @@ -//! Crds Gossip Pull overlay +//! Crds Gossip Pull overlay. +//! //! This module implements the anti-entropy protocol for the network. //! //! The basic strategy is as follows: +//! //! 1. Construct a bloom filter of the local data set //! 2. Randomly ask a node on the network for data that is not contained in the bloom filter. //! @@ -186,7 +188,7 @@ pub struct ProcessPullStats { } pub struct CrdsGossipPull { - /// timestamp of last request + /// Timestamp of last request pull_request_time: RwLock>, // Hash value and record time (ms) of the pull responses which failed to be // inserted in crds table; Preserved to stop the sender to send back the @@ -210,7 +212,7 @@ impl Default for CrdsGossipPull { } } impl CrdsGossipPull { - /// generate a random request + /// Generate a random request #[allow(clippy::too_many_arguments)] pub(crate) fn new_pull_request( &self, @@ -326,7 +328,8 @@ impl CrdsGossipPull { .collect() } - /// time when a request to `from` was initiated + /// Time when a request to `from` was initiated. + /// /// This is used for weighted random selection during `new_pull_request` /// It's important to use the local nodes request creation time as the weight /// instead of the response received time otherwise failed nodes will increase their weight. @@ -334,7 +337,7 @@ impl CrdsGossipPull { self.pull_request_time.write().unwrap().put(from, now); } - /// process a pull request + /// Process a pull request pub(crate) fn process_pull_requests(crds: &RwLock, callers: I, now: u64) where I: IntoIterator, @@ -409,7 +412,7 @@ impl CrdsGossipPull { (active_values, expired_values, failed_inserts) } - /// process a vec of pull responses + /// Process a vec of pull responses pub(crate) fn process_pull_responses( &self, crds: &RwLock, @@ -499,7 +502,7 @@ impl CrdsGossipPull { filters.into() } - /// filter values that fail the bloom filter up to max_bytes + /// Filter values that fail the bloom filter up to `max_bytes`. fn filter_crds_values( crds: &RwLock, filters: &[(CrdsValue, CrdsFilter)], diff --git a/gossip/src/crds_gossip_push.rs b/gossip/src/crds_gossip_push.rs index fce4b633c..e1d502d5b 100644 --- a/gossip/src/crds_gossip_push.rs +++ b/gossip/src/crds_gossip_push.rs @@ -1,9 +1,12 @@ -//! Crds Gossip Push overlay +//! Crds Gossip Push overlay. +//! //! This module is used to propagate recently created CrdsValues across the network -//! Eager push strategy is based on Plumtree -//! http://asc.di.fct.unl.pt/~jleitao/pdf/srds07-leitao.pdf +//! Eager push strategy is based on [Plumtree]. +//! +//! [Plumtree]: http://asc.di.fct.unl.pt/~jleitao/pdf/srds07-leitao.pdf //! //! Main differences are: +//! //! 1. There is no `max hop`. Messages are signed with a local wallclock. If they are outside of //! the local nodes wallclock window they are dropped silently. //! 2. The prune set is stored in a Bloom filter. @@ -50,14 +53,15 @@ pub const CRDS_GOSSIP_PRUNE_MIN_INGRESS_NODES: usize = 3; const PUSH_ACTIVE_TIMEOUT_MS: u64 = 60_000; pub struct CrdsGossipPush { - /// max bytes per message + /// Max bytes per message max_bytes: usize, - /// active set of validators for push + /// Active set of validators for push active_set: RwLock>>, /// Cursor into the crds table for values to push. crds_cursor: Mutex, /// Cache that tracks which validators a message was received from /// bool indicates it has been pruned. + /// /// This cache represents a lagging view of which validators /// currently have this node in their `active_set` #[allow(clippy::type_complexity)] @@ -199,7 +203,8 @@ impl CrdsGossipPush { now.saturating_sub(self.msg_timeout)..=now.saturating_add(self.msg_timeout) } - /// process a push message to the network + /// Process a push message to the network. + /// /// Returns origins' pubkeys of upserted values. pub(crate) fn process_push_message( &self, @@ -246,6 +251,7 @@ impl CrdsGossipPush { } /// New push message to broadcast to peers. + /// /// Returns a list of Pubkeys for the selected peers and a list of values to send to all the /// peers. /// The list of push messages is created such that all the randomly selected peers have not @@ -306,7 +312,7 @@ impl CrdsGossipPush { push_messages } - /// add the `from` to the peer's filter of nodes + /// Add the `from` to the peer's filter of nodes. pub fn process_prune_msg(&self, self_pubkey: &Pubkey, peer: &Pubkey, origins: &[Pubkey]) { if let Some(filter) = self.active_set.read().unwrap().get(peer) { for origin in origins { @@ -322,7 +328,10 @@ impl CrdsGossipPush { cmp::min(num_active, (num_active - active_set_len) + num) } - /// refresh the push active set + /// Refresh the push active set. + /// + /// # Arguments + /// /// * ratio - active_set.len()/ratio is the number of actives to rotate pub(crate) fn refresh_push_active_set( &self, @@ -429,7 +438,7 @@ impl CrdsGossipPush { .collect() } - /// purge received push message cache + /// Purge received push message cache pub(crate) fn purge_old_received_cache(&self, min_time: u64) { self.received_cache.lock().unwrap().retain(|_, v| { v.retain(|_, (_, t)| *t > min_time); diff --git a/ledger/src/blockstore/blockstore_purge.rs b/ledger/src/blockstore/blockstore_purge.rs index c11ba606c..5f64296fd 100644 --- a/ledger/src/blockstore/blockstore_purge.rs +++ b/ledger/src/blockstore/blockstore_purge.rs @@ -8,7 +8,7 @@ pub struct PurgeStats { } impl Blockstore { - /// Silently deletes all blockstore column families in the range [from_slot,to_slot] + /// Silently deletes all blockstore column families in the range \[from_slot,to_slot\] /// Dangerous; Use with care: /// Does not check for integrity and does not update slot metas that refer to deleted slots /// Modifies multiple column families simultaneously @@ -57,7 +57,7 @@ impl Blockstore { } /// Ensures that the SlotMeta::next_slots vector for all slots contain no references in the - /// [from_slot,to_slot] range + /// \[from_slot,to_slot\] range /// /// Dangerous; Use with care pub fn purge_from_next_slots(&self, from_slot: Slot, to_slot: Slot) { diff --git a/programs/vote/src/vote_instruction.rs b/programs/vote/src/vote_instruction.rs index ac9c863d0..f8aa30ebb 100644 --- a/programs/vote/src/vote_instruction.rs +++ b/programs/vote/src/vote_instruction.rs @@ -57,59 +57,59 @@ pub enum VoteInstruction { /// Initialize a vote account /// /// # Account references - /// 0. [WRITE] Uninitialized vote account - /// 1. [] Rent sysvar - /// 2. [] Clock sysvar - /// 3. [SIGNER] New validator identity (node_pubkey) + /// 0. `[WRITE]` Uninitialized vote account + /// 1. `[]` Rent sysvar + /// 2. `[]` Clock sysvar + /// 3. `[SIGNER]` New validator identity (node_pubkey) InitializeAccount(VoteInit), /// Authorize a key to send votes or issue a withdrawal /// /// # Account references - /// 0. [WRITE] Vote account to be updated with the Pubkey for authorization - /// 1. [] Clock sysvar - /// 2. [SIGNER] Vote or withdraw authority + /// 0. `[WRITE]` Vote account to be updated with the Pubkey for authorization + /// 1. `[]` Clock sysvar + /// 2. `[SIGNER]` Vote or withdraw authority Authorize(Pubkey, VoteAuthorize), /// A Vote instruction with recent votes /// /// # Account references - /// 0. [WRITE] Vote account to vote with - /// 1. [] Slot hashes sysvar - /// 2. [] Clock sysvar - /// 3. [SIGNER] Vote authority + /// 0. `[WRITE]` Vote account to vote with + /// 1. `[]` Slot hashes sysvar + /// 2. `[]` Clock sysvar + /// 3. `[SIGNER]` Vote authority Vote(Vote), /// Withdraw some amount of funds /// /// # Account references - /// 0. [WRITE] Vote account to withdraw from - /// 1. [WRITE] Recipient account - /// 2. [SIGNER] Withdraw authority + /// 0. `[WRITE]` Vote account to withdraw from + /// 1. `[WRITE]` Recipient account + /// 2. `[SIGNER]` Withdraw authority Withdraw(u64), /// Update the vote account's validator identity (node_pubkey) /// /// # Account references - /// 0. [WRITE] Vote account to be updated with the given authority public key - /// 1. [SIGNER] New validator identity (node_pubkey) - /// 2. [SIGNER] Withdraw authority + /// 0. `[WRITE]` Vote account to be updated with the given authority public key + /// 1. `[SIGNER]` New validator identity (node_pubkey) + /// 2. `[SIGNER]` Withdraw authority UpdateValidatorIdentity, /// Update the commission for the vote account /// /// # Account references - /// 0. [WRITE] Vote account to be updated - /// 1. [SIGNER] Withdraw authority + /// 0. `[WRITE]` Vote account to be updated + /// 1. `[SIGNER]` Withdraw authority UpdateCommission(u8), /// A Vote instruction with recent votes /// /// # Account references - /// 0. [WRITE] Vote account to vote with - /// 1. [] Slot hashes sysvar - /// 2. [] Clock sysvar - /// 3. [SIGNER] Vote authority + /// 0. `[WRITE]` Vote account to vote with + /// 1. `[]` Slot hashes sysvar + /// 2. `[]` Clock sysvar + /// 3. `[SIGNER]` Vote authority VoteSwitch(Vote, Hash), /// Authorize a key to send votes or issue a withdrawal @@ -118,10 +118,10 @@ pub enum VoteInstruction { /// or withdraw authority must also be a signer. /// /// # Account references - /// 0. [WRITE] Vote account to be updated with the Pubkey for authorization - /// 1. [] Clock sysvar - /// 2. [SIGNER] Vote or withdraw authority - /// 3. [SIGNER] New vote or withdraw authority + /// 0. `[WRITE]` Vote account to be updated with the Pubkey for authorization + /// 1. `[]` Clock sysvar + /// 2. `[SIGNER]` Vote or withdraw authority + /// 3. `[SIGNER]` New vote or withdraw authority AuthorizeChecked(VoteAuthorize), } diff --git a/runtime/src/append_vec.rs b/runtime/src/append_vec.rs index 1f8f9744e..7811e91af 100644 --- a/runtime/src/append_vec.rs +++ b/runtime/src/append_vec.rs @@ -1,5 +1,8 @@ -//! Persistent storage for accounts. For more information, see: -//! https://docs.solana.com/implemented-proposals/persistent-account-storage +//! Persistent storage for accounts. +//! +//! For more information, see: +//! +//! use log::*; use memmap2::MmapMut; diff --git a/runtime/src/bloom.rs b/runtime/src/bloom.rs index 2fde18a03..ae160a30a 100644 --- a/runtime/src/bloom.rs +++ b/runtime/src/bloom.rs @@ -67,10 +67,12 @@ impl Bloom { _phantom: PhantomData::default(), } } - /// create filter optimal for num size given the `FALSE_RATE` - /// the keys are randomized for picking data out of a collision resistant hash of size - /// `keysize` bytes - /// https://hur.st/bloomfilter/ + /// Create filter optimal for num size given the `FALSE_RATE`. + /// + /// The keys are randomized for picking data out of a collision resistant hash of size + /// `keysize` bytes. + /// + /// See . pub fn random(num_items: usize, false_rate: f64, max_bits: usize) -> Self { let m = Self::num_bits(num_items as f64, false_rate); let num_bits = cmp::max(1, cmp::min(m as usize, max_bits)); diff --git a/sdk/program/src/loader_upgradeable_instruction.rs b/sdk/program/src/loader_upgradeable_instruction.rs index 76fd0e34e..76d199363 100644 --- a/sdk/program/src/loader_upgradeable_instruction.rs +++ b/sdk/program/src/loader_upgradeable_instruction.rs @@ -15,16 +15,16 @@ pub enum UpgradeableLoaderInstruction { /// Otherwise another party may initialize the account. /// /// # Account references - /// 0. [writable] source account to initialize. - /// 1. [] Buffer authority, optional, if omitted then the buffer will be + /// 0. `[writable]` source account to initialize. + /// 1. `[]` Buffer authority, optional, if omitted then the buffer will be /// immutable. InitializeBuffer, /// Write program data into a Buffer account. /// /// # Account references - /// 0. [writable] Buffer account to write program data to. - /// 1. [signer] Buffer authority + /// 0. `[writable]` Buffer account to write program data to. + /// 1. `[signer]` Buffer authority Write { /// Offset at which to write the given bytes. offset: u32, @@ -46,10 +46,15 @@ pub enum UpgradeableLoaderInstruction { /// The ProgramData address is derived from the Program account's address as /// follows: /// - /// `let (program_data_address, _) = Pubkey::find_program_address( + /// ``` + /// # use solana_program::pubkey::Pubkey; + /// # use solana_program::bpf_loader_upgradeable; + /// # let program_address = &[]; + /// let (program_data_address, _) = Pubkey::find_program_address( /// &[program_address], /// &bpf_loader_upgradeable::id() - /// );` + /// ); + /// ``` /// /// The `DeployWithMaxDataLen` instruction does not require the ProgramData /// account be a signer and therefore MUST be included within the same @@ -58,17 +63,17 @@ pub enum UpgradeableLoaderInstruction { /// account. /// /// # Account references - /// 0. [signer] The payer account that will pay to create the ProgramData + /// 0. `[signer]` The payer account that will pay to create the ProgramData /// account. - /// 1. [writable] The uninitialized ProgramData account. - /// 2. [writable] The uninitialized Program account. - /// 3. [writable] The Buffer account where the program data has been + /// 1. `[writable]` The uninitialized ProgramData account. + /// 2. `[writable]` The uninitialized Program account. + /// 3. `[writable]` The Buffer account where the program data has been /// written. The buffer account's authority must match the program's /// authority - /// 4. [] Rent sysvar. - /// 5. [] Clock sysvar. - /// 6. [] System program (`solana_sdk::system_program::id()`). - /// 7. [signer] The program's authority + /// 4. `[]` Rent sysvar. + /// 5. `[]` Clock sysvar. + /// 6. `[]` System program (`solana_sdk::system_program::id()`). + /// 7. `[signer]` The program's authority DeployWithMaxDataLen { /// Maximum length that the program can be upgraded to. max_data_len: usize, @@ -85,15 +90,15 @@ pub enum UpgradeableLoaderInstruction { /// balance at zero. /// /// # Account references - /// 0. [writable] The ProgramData account. - /// 1. [writable] The Program account. - /// 2. [writable] The Buffer account where the program data has been + /// 0. `[writable]` The ProgramData account. + /// 1. `[writable]` The Program account. + /// 2. `[writable]` The Buffer account where the program data has been /// written. The buffer account's authority must match the program's /// authority - /// 3. [writable] The spill account. - /// 4. [] Rent sysvar. - /// 5. [] Clock sysvar. - /// 6. [signer] The program's authority. + /// 3. `[writable]` The spill account. + /// 4. `[]` Rent sysvar. + /// 5. `[]` Clock sysvar. + /// 6. `[signer]` The program's authority. Upgrade, /// Set a new authority that is allowed to write the buffer or upgrade the diff --git a/sdk/program/src/program_option.rs b/sdk/program/src/program_option.rs index 7ac60442d..255ba1468 100644 --- a/sdk/program/src/program_option.rs +++ b/sdk/program/src/program_option.rs @@ -880,7 +880,7 @@ impl Clone for COption { } impl Default for COption { - /// Returns [`COption::None`][COption::COption::None]. + /// Returns [`COption::None`][COption::None]. /// /// # Examples /// diff --git a/sdk/program/src/stake/instruction.rs b/sdk/program/src/stake/instruction.rs index 6fadfd7a0..fc0dec91a 100644 --- a/sdk/program/src/stake/instruction.rs +++ b/sdk/program/src/stake/instruction.rs @@ -59,8 +59,8 @@ pub enum StakeInstruction { /// Initialize a stake with lockup and authorization information /// /// # Account references - /// 0. [WRITE] Uninitialized stake account - /// 1. [] Rent sysvar + /// 0. `[WRITE]` Uninitialized stake account + /// 1. `[]` Rent sysvar /// /// Authorized carries pubkeys that must sign staker transactions /// and withdrawer transactions. @@ -70,22 +70,22 @@ pub enum StakeInstruction { /// Authorize a key to manage stake or withdrawal /// /// # Account references - /// 0. [WRITE] Stake account to be updated - /// 1. [] Clock sysvar - /// 2. [SIGNER] The stake or withdraw authority - /// 3. Optional: [SIGNER] Lockup authority, if updating StakeAuthorize::Withdrawer before + /// 0. `[WRITE]` Stake account to be updated + /// 1. `[]` Clock sysvar + /// 2. `[SIGNER]` The stake or withdraw authority + /// 3. Optional: `[SIGNER]` Lockup authority, if updating StakeAuthorize::Withdrawer before /// lockup expiration Authorize(Pubkey, StakeAuthorize), /// Delegate a stake to a particular vote account /// /// # Account references - /// 0. [WRITE] Initialized stake account to be delegated - /// 1. [] Vote account to which this stake will be delegated - /// 2. [] Clock sysvar - /// 3. [] Stake history sysvar that carries stake warmup/cooldown history - /// 4. [] Address of config account that carries stake config - /// 5. [SIGNER] Stake authority + /// 0. `[WRITE]` Initialized stake account to be delegated + /// 1. `[]` Vote account to which this stake will be delegated + /// 2. `[]` Clock sysvar + /// 3. `[]` Stake history sysvar that carries stake warmup/cooldown history + /// 4. `[]` Address of config account that carries stake config + /// 5. `[SIGNER]` Stake authority /// /// The entire balance of the staking account is staked. DelegateStake /// can be called multiple times, but re-delegation is delayed @@ -95,20 +95,20 @@ pub enum StakeInstruction { /// Split u64 tokens and stake off a stake account into another stake account. /// /// # Account references - /// 0. [WRITE] Stake account to be split; must be in the Initialized or Stake state - /// 1. [WRITE] Uninitialized stake account that will take the split-off amount - /// 2. [SIGNER] Stake authority + /// 0. `[WRITE]` Stake account to be split; must be in the Initialized or Stake state + /// 1. `[WRITE]` Uninitialized stake account that will take the split-off amount + /// 2. `[SIGNER]` Stake authority Split(u64), /// Withdraw unstaked lamports from the stake account /// /// # Account references - /// 0. [WRITE] Stake account from which to withdraw - /// 1. [WRITE] Recipient account - /// 2. [] Clock sysvar - /// 3. [] Stake history sysvar that carries stake warmup/cooldown history - /// 4. [SIGNER] Withdraw authority - /// 5. Optional: [SIGNER] Lockup authority, if before lockup expiration + /// 0. `[WRITE]` Stake account from which to withdraw + /// 1. `[WRITE]` Recipient account + /// 2. `[]` Clock sysvar + /// 3. `[]` Stake history sysvar that carries stake warmup/cooldown history + /// 4. `[SIGNER]` Withdraw authority + /// 5. Optional: `[SIGNER]` Lockup authority, if before lockup expiration /// /// The u64 is the portion of the stake account balance to be withdrawn, /// must be `<= StakeAccount.lamports - staked_lamports`. @@ -117,9 +117,9 @@ pub enum StakeInstruction { /// Deactivates the stake in the account /// /// # Account references - /// 0. [WRITE] Delegated stake account - /// 1. [] Clock sysvar - /// 2. [SIGNER] Stake authority + /// 0. `[WRITE]` Delegated stake account + /// 1. `[]` Clock sysvar + /// 2. `[SIGNER]` Stake authority Deactivate, /// Set stake lockup @@ -128,8 +128,8 @@ pub enum StakeInstruction { /// If a lockup is active, the lockup custodian may update the lockup parameters /// /// # Account references - /// 0. [WRITE] Initialized stake account - /// 1. [SIGNER] Lockup authority or withdraw authority + /// 0. `[WRITE]` Initialized stake account + /// 1. `[SIGNER]` Lockup authority or withdraw authority SetLockup(LockupArgs), /// Merge two stake accounts. @@ -151,20 +151,20 @@ pub enum StakeInstruction { /// non-zero effective stake. /// /// # Account references - /// 0. [WRITE] Destination stake account for the merge - /// 1. [WRITE] Source stake account for to merge. This account will be drained - /// 2. [] Clock sysvar - /// 3. [] Stake history sysvar that carries stake warmup/cooldown history - /// 4. [SIGNER] Stake authority + /// 0. `[WRITE]` Destination stake account for the merge + /// 1. `[WRITE]` Source stake account for to merge. This account will be drained + /// 2. `[]` Clock sysvar + /// 3. `[]` Stake history sysvar that carries stake warmup/cooldown history + /// 4. `[SIGNER]` Stake authority Merge, /// Authorize a key to manage stake or withdrawal with a derived key /// /// # Account references - /// 0. [WRITE] Stake account to be updated - /// 1. [SIGNER] Base key of stake or withdraw authority - /// 2. [] Clock sysvar - /// 3. Optional: [SIGNER] Lockup authority, if updating StakeAuthorize::Withdrawer before + /// 0. `[WRITE]` Stake account to be updated + /// 1. `[SIGNER]` Base key of stake or withdraw authority + /// 2. `[]` Clock sysvar + /// 3. Optional: `[SIGNER]` Lockup authority, if updating StakeAuthorize::Withdrawer before /// lockup expiration AuthorizeWithSeed(AuthorizeWithSeedArgs), @@ -174,10 +174,10 @@ pub enum StakeInstruction { /// must be a signer, and no lockup is applied to the account. /// /// # Account references - /// 0. [WRITE] Uninitialized stake account - /// 1. [] Rent sysvar - /// 2. [] The stake authority - /// 3. [SIGNER] The withdraw authority + /// 0. `[WRITE]` Uninitialized stake account + /// 1. `[]` Rent sysvar + /// 2. `[]` The stake authority + /// 3. `[SIGNER]` The withdraw authority /// InitializeChecked, @@ -187,11 +187,11 @@ pub enum StakeInstruction { /// stake or withdraw authority must also be a signer. /// /// # Account references - /// 0. [WRITE] Stake account to be updated - /// 1. [] Clock sysvar - /// 2. [SIGNER] The stake or withdraw authority - /// 3. [SIGNER] The new stake or withdraw authority - /// 4. Optional: [SIGNER] Lockup authority, if updating StakeAuthorize::Withdrawer before + /// 0. `[WRITE]` Stake account to be updated + /// 1. `[]` Clock sysvar + /// 2. `[SIGNER]` The stake or withdraw authority + /// 3. `[SIGNER]` The new stake or withdraw authority + /// 4. Optional: `[SIGNER]` Lockup authority, if updating StakeAuthorize::Withdrawer before /// lockup expiration AuthorizeChecked(StakeAuthorize), @@ -201,11 +201,11 @@ pub enum StakeInstruction { /// the new stake or withdraw authority must also be a signer. /// /// # Account references - /// 0. [WRITE] Stake account to be updated - /// 1. [SIGNER] Base key of stake or withdraw authority - /// 2. [] Clock sysvar - /// 3. [SIGNER] The new stake or withdraw authority - /// 4. Optional: [SIGNER] Lockup authority, if updating StakeAuthorize::Withdrawer before + /// 0. `[WRITE]` Stake account to be updated + /// 1. `[SIGNER]` Base key of stake or withdraw authority + /// 2. `[]` Clock sysvar + /// 3. `[SIGNER]` The new stake or withdraw authority + /// 4. Optional: `[SIGNER]` Lockup authority, if updating StakeAuthorize::Withdrawer before /// lockup expiration AuthorizeCheckedWithSeed(AuthorizeCheckedWithSeedArgs), @@ -218,9 +218,9 @@ pub enum StakeInstruction { /// If a lockup is active, the lockup custodian may update the lockup parameters /// /// # Account references - /// 0. [WRITE] Initialized stake account - /// 1. [SIGNER] Lockup authority or withdraw authority - /// 2. Optional: [SIGNER] New lockup authority + /// 0. `[WRITE]` Initialized stake account + /// 1. `[SIGNER]` Lockup authority or withdraw authority + /// 2. Optional: `[SIGNER]` New lockup authority SetLockupChecked(LockupCheckedArgs), } diff --git a/sdk/program/src/system_instruction.rs b/sdk/program/src/system_instruction.rs index 5294e9edb..ede5c6dc6 100644 --- a/sdk/program/src/system_instruction.rs +++ b/sdk/program/src/system_instruction.rs @@ -58,8 +58,8 @@ pub enum SystemInstruction { /// Create a new account /// /// # Account references - /// 0. [WRITE, SIGNER] Funding account - /// 1. [WRITE, SIGNER] New account + /// 0. `[WRITE, SIGNER]` Funding account + /// 1. `[WRITE, SIGNER]` New account CreateAccount { /// Number of lamports to transfer to the new account lamports: u64, @@ -74,7 +74,7 @@ pub enum SystemInstruction { /// Assign account to a program /// /// # Account references - /// 0. [WRITE, SIGNER] Assigned account public key + /// 0. `[WRITE, SIGNER]` Assigned account public key Assign { /// Owner program account owner: Pubkey, @@ -83,16 +83,16 @@ pub enum SystemInstruction { /// Transfer lamports /// /// # Account references - /// 0. [WRITE, SIGNER] Funding account - /// 1. [WRITE] Recipient account + /// 0. `[WRITE, SIGNER]` Funding account + /// 1. `[WRITE]` Recipient account Transfer { lamports: u64 }, /// Create a new account at an address derived from a base pubkey and a seed /// /// # Account references - /// 0. [WRITE, SIGNER] Funding account - /// 1. [WRITE] Created account - /// 2. [SIGNER] (optional) Base account; the account matching the base Pubkey below must be + /// 0. `[WRITE, SIGNER]` Funding account + /// 1. `[WRITE]` Created account + /// 2. `[SIGNER]` (optional) Base account; the account matching the base Pubkey below must be /// provided as a signer, but may be the same as the funding account /// and provided as account 0 CreateAccountWithSeed { @@ -115,19 +115,19 @@ pub enum SystemInstruction { /// Consumes a stored nonce, replacing it with a successor /// /// # Account references - /// 0. [WRITE] Nonce account - /// 1. [] RecentBlockhashes sysvar - /// 2. [SIGNER] Nonce authority + /// 0. `[WRITE]` Nonce account + /// 1. `[]` RecentBlockhashes sysvar + /// 2. `[SIGNER]` Nonce authority AdvanceNonceAccount, /// Withdraw funds from a nonce account /// /// # Account references - /// 0. [WRITE] Nonce account - /// 1. [WRITE] Recipient account - /// 2. [] RecentBlockhashes sysvar - /// 3. [] Rent sysvar - /// 4. [SIGNER] Nonce authority + /// 0. `[WRITE]` Nonce account + /// 1. `[WRITE]` Recipient account + /// 2. `[]` RecentBlockhashes sysvar + /// 3. `[]` Rent sysvar + /// 4. `[SIGNER]` Nonce authority /// /// The `u64` parameter is the lamports to withdraw, which must leave the /// account balance above the rent exempt reserve or at zero. @@ -136,9 +136,9 @@ pub enum SystemInstruction { /// Drive state of Uninitalized nonce account to Initialized, setting the nonce value /// /// # Account references - /// 0. [WRITE] Nonce account - /// 1. [] RecentBlockhashes sysvar - /// 2. [] Rent sysvar + /// 0. `[WRITE]` Nonce account + /// 1. `[]` RecentBlockhashes sysvar + /// 2. `[]` Rent sysvar /// /// The `Pubkey` parameter specifies the entity authorized to execute nonce /// instruction on the account @@ -150,8 +150,8 @@ pub enum SystemInstruction { /// Change the entity authorized to execute nonce instructions on the account /// /// # Account references - /// 0. [WRITE] Nonce account - /// 1. [SIGNER] Nonce authority + /// 0. `[WRITE]` Nonce account + /// 1. `[SIGNER]` Nonce authority /// /// The `Pubkey` parameter identifies the entity to authorize AuthorizeNonceAccount(Pubkey), @@ -159,7 +159,7 @@ pub enum SystemInstruction { /// Allocate space in a (possibly new) account without funding /// /// # Account references - /// 0. [WRITE, SIGNER] New account + /// 0. `[WRITE, SIGNER]` New account Allocate { /// Number of bytes of memory to allocate space: u64, @@ -169,8 +169,8 @@ pub enum SystemInstruction { /// derived from a base public key and a seed /// /// # Account references - /// 0. [WRITE] Allocated account - /// 1. [SIGNER] Base account + /// 0. `[WRITE]` Allocated account + /// 1. `[SIGNER]` Base account AllocateWithSeed { /// Base public key base: Pubkey, @@ -188,8 +188,8 @@ pub enum SystemInstruction { /// Assign account to a program based on a seed /// /// # Account references - /// 0. [WRITE] Assigned account - /// 1. [SIGNER] Base account + /// 0. `[WRITE]` Assigned account + /// 1. `[SIGNER]` Base account AssignWithSeed { /// Base public key base: Pubkey, @@ -204,9 +204,9 @@ pub enum SystemInstruction { /// Transfer lamports from a derived address /// /// # Account references - /// 0. [WRITE] Funding account - /// 1. [SIGNER] Base for funding account - /// 2. [WRITE] Recipient account + /// 0. `[WRITE]` Funding account + /// 1. `[SIGNER]` Base for funding account + /// 2. `[WRITE]` Recipient account TransferWithSeed { /// Amount to transfer lamports: u64, diff --git a/sdk/src/process_instruction.rs b/sdk/src/process_instruction.rs index d740c87e8..b384dca91 100644 --- a/sdk/src/process_instruction.rs +++ b/sdk/src/process_instruction.rs @@ -243,7 +243,10 @@ pub mod stable_log { /// Log a program invoke. /// /// The general form is: - /// "Program
invoke []" + /// + /// ```notrust + /// "Program
invoke []" + /// ``` pub fn program_invoke( logger: &Rc>, program_id: &Pubkey, @@ -255,7 +258,11 @@ pub mod stable_log { /// Log a message from the program itself. /// /// The general form is: - /// "Program log: " + /// + /// ```notrust + /// "Program log: " + /// ``` + /// /// That is, any program-generated output is guaranteed to be prefixed by "Program log: " pub fn program_log(logger: &Rc>, message: &str) { ic_logger_msg!(logger, "Program log: {}", message); @@ -264,7 +271,10 @@ pub mod stable_log { /// Log successful program execution. /// /// The general form is: - /// "Program
success" + /// + /// ```notrust + /// "Program
success" + /// ``` pub fn program_success(logger: &Rc>, program_id: &Pubkey) { ic_logger_msg!(logger, "Program {} success", program_id); } @@ -272,7 +282,10 @@ pub mod stable_log { /// Log program execution failure /// /// The general form is: - /// "Program
failed: " + /// + /// ```notrust + /// "Program
failed: " + /// ``` pub fn program_failure( logger: &Rc>, program_id: &Pubkey,