gaspersic/solana
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Eliminate doc warnings and fix some markdown (#18566)

Browse Source 
* 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
This commit is contained in:
Brian Anderson
2021-07-15 19:40:07 -05:00
committed by GitHub
parent aeb30fa873
commit 37ee0b5599
12 changed files with 208 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
sdk/program/src/loader_upgradeable_instruction.rs
View File

@ -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

2
sdk/program/src/program_option.rs
View File

@ -880,7 +880,7 @@ impl<T: Clone> Clone for COption<T> {
}
impl<T> Default for COption<T> {
/// Returns [`COption::None`][COption::COption::None].
/// Returns [`COption::None`][COption::None].
///
/// # Examples
///

104
sdk/program/src/stake/instruction.rs
View File

@ -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),
}

58
sdk/program/src/system_instruction.rs
View File

@ -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,