Cleanup program docs (bp #10283)

programs/stake/src/stake_instruction.rs

@@ -43,86 +43,75 @@ impl<E> DecodeError<E> for StakeError {
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)]
 pub enum StakeInstruction {
-    /// `Initialize` a stake with Lockup and Authorized information
+    /// Initialize a stake with lockup and authorization information
     ///
-    /// Expects 2 Accounts:
-    ///    0 - Uninitialized StakeAccount
-    ///    1 - Rent sysvar
+    /// # Account references
+    ///   0. [WRITE] Uninitialized stake account
+    ///   1. [] Rent sysvar
     ///
     /// Authorized carries pubkeys that must sign staker transactions
     ///   and withdrawer transactions.
     /// Lockup carries information about withdrawal restrictions
-    ///
     Initialize(Authorized, Lockup),
 
     /// Authorize a key to manage stake or withdrawal
-    ///    requires Authorized::staker or Authorized::withdrawer
-    ///    signature, depending on which key's being updated
     ///
-    /// Expects 2 Accounts:
-    ///    0 - StakeAccount to be updated with the Pubkey for
-    ///          authorization
-    ///    1 - (reserved for future use) Clock sysvar Account that carries
-    ///        clock bank epoch
+    /// # Account references
+    ///   0. [WRITE] Stake account to be updated
+    ///   1. [] (reserved for future use) Clock sysvar
+    ///   2. [SIGNER] The stake or withdraw authority
     Authorize(Pubkey, StakeAuthorize),
 
-    /// `Delegate` a stake to a particular vote account
-    ///    requires Authorized::staker signature
+    /// Delegate a stake to a particular vote account
     ///
-    /// Expects 4 Accounts:
-    ///    0 - Initialized StakeAccount to be delegated
-    ///    1 - VoteAccount to which this Stake will be delegated
-    ///    2 - Clock sysvar Account that carries clock bank epoch
-    ///    3 - Config Account that carries stake config
+    /// # 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
     ///
     /// The entire balance of the staking account is staked.  DelegateStake
     ///   can be called multiple times, but re-delegation is delayed
     ///   by one epoch
-    ///
     DelegateStake,
 
-    /// Split u64 tokens and stake off a stake account into another stake
-    ///   account. Requires Authorized::staker signature and the
-    ///   signature of the split-off stake address.
-    ///
-    /// The source stake must be either Initialized or a Stake.
-    ///
-    /// Expects 2 Accounts:
-    ///    0 - StakeAccount to be split
-    ///    1 - Uninitialized StakeAcount that will take the split-off amount
+    /// 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
     Split(u64),
 
     /// Withdraw unstaked lamports from the stake account
-    ///    requires Authorized::withdrawer signature.  If withdrawal
-    ///    is before lockup has expired, also requires signature
-    ///    of the lockup custodian.
     ///
-    /// Expects 4 Accounts:
-    ///    0 - StakeAccount from which to withdraw
-    ///    1 - Account to which the lamports will be transferred
-    ///    2 - Syscall Account that carries epoch
-    ///    3 - StakeHistory sysvar that carries stake warmup/cooldown history
+    /// # 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
     ///
-    /// The u64 is the portion of the Stake account balance to be withdrawn,
-    ///    must be <= StakeAccount.lamports - staked lamports.
+    /// The u64 is the portion of the stake account balance to be withdrawn,
+    ///    must be `<= StakeAccount.lamports - staked_lamports`.
     Withdraw(u64),
 
     /// Deactivates the stake in the account
-    ///    requires Authorized::staker signature
-    ///
-    /// Expects 2 Accounts:
-    ///    0 - Delegate StakeAccount
-    ///    1 - Syscall Account that carries epoch
     ///
+    /// # Account references
+    ///   0. [WRITE] Delegated stake account
+    ///   1. [] Clock sysvar
+    ///   2. [SIGNER] Stake authority
     Deactivate,
 
     /// Set stake lockup
-    ///    requires Lockup::custodian signature
-    ///
-    /// Expects 1 Account:
-    ///    0 - initialized StakeAccount
     ///
+    /// # Account references
+    ///   0. [WRITE] Initialized stake account
+    ///   1. [SIGNER] Lockup authority
     SetLockup(LockupArgs),
 }
 

programs/vote/src/vote_instruction.rs

@@ -51,59 +51,55 @@ impl<E> DecodeError<E> for VoteError {
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)]
 pub enum VoteInstruction {
-    /// Initialize the VoteState for this `vote account`
-    ///    requires VoteInit::node_pubkey signature
-    ///
-    /// Expects 3 Accounts:
-    ///    0 - Uninitialized Vote account
-    ///    1 - Rent sysvar
-    ///    2 - Clock sysvar
+    /// Initialize a vote account
     ///
+    /// # Account references
+    ///   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
-    ///    requires authorized voter or authorized withdrawer signature,
-    ///    depending on which key's being updated
-    ///
-    /// Expects 2 Accounts:
-    ///    0 - Vote account to be updated with the Pubkey for authorization
-    ///    1 - Clock sysvar
     ///
+    /// # Account references
+    ///   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
-    ///    requires authorized voter signature
     ///
-    /// Expects 3 Accounts:
-    ///    0 - Vote account to vote with
-    ///    1 - Slot hashes sysvar
-    ///    2 - Clock sysvar
+    /// # Account references
+    ///   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
-    ///    requires authorized withdrawer signature
     ///
-    /// Expects 2 Accounts:
-    ///    0 - Vote account to withdraw from
-    ///    1 - Destination account for the withdrawal
+    /// # Account references
+    ///   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)
-    ///    requires authorized withdrawer and new validator identity signature
-    ///
-    /// Expects 2 Accounts:
-    ///    0 - Vote account to be updated with the Pubkey for authorization
-    ///    1 - New 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
     UpdateValidatorIdentity,
 
     /// A Vote instruction with recent votes
-    ///    requires authorized voter signature
     ///
-    /// Expects 3 Accounts:
-    ///    0 - Vote account to vote with
-    ///    1 - Slot hashes sysvar
-    ///    2 - Clock sysvar
+    /// # Account references
+    ///   0. [WRITE] Vote account to vote with
+    ///   1. [] Slot hashes sysvar
+    ///   2. [] Clock sysvar
+    ///   3. [SIGNER] Vote authority
     VoteSwitch(Vote, Hash),
 }
 

sdk/src/loader_instruction.rs

@@ -8,23 +8,25 @@ use crate::{
 pub enum LoaderInstruction {
     /// Write program data into an account
     ///
-    /// * key[0] - the account to write into.
-    ///
-    /// The transaction must be signed by key[0]
+    /// # Account references
+    ///   0. [WRITE, SIGNER] Account to write to
     Write {
+        /// Offset at which to write the given bytes
         offset: u32,
+
+        /// Serialized program data
         #[serde(with = "serde_bytes")]
         bytes: Vec<u8>,
     },
 
-    /// Finalize an account loaded with program data for execution.
-    /// The exact preparation steps is loader specific but on success the loader must set the executable
-    /// bit of the Account
+    /// Finalize an account loaded with program data for execution
     ///
-    /// * key[0] - the account to prepare for execution
-    /// * key[1] - rent sysvar account
+    /// The exact preparation steps is loader specific but on success the loader must set the executable
+    /// bit of the account.
     ///
-    /// The transaction must be signed by key[0]
+    /// # Account references
+    ///   0. [WRITE, SIGNER] The account to prepare for execution
+    ///   1. [] Rent sysvar
     Finalize,
 }