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

@@ -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<I>(
         &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
+    /// Refresh the push active set.
-    /// * ratio - number of actives to rotate
     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<I>(&self, callers: I, now: u64)
     where
         I: IntoIterator<Item = CrdsValue>,
@@ -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<S: std::hash::BuildHasher>(id: &Pubkey, stakes: &HashMap<Pubkey, u64, S>) -> 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;

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<LruCache<Pubkey, /*timestamp:*/ u64>>,
     // 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<I>(crds: &RwLock<Crds>, callers: I, now: u64)
     where
         I: IntoIterator<Item = CrdsValue>,
@@ -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<Crds>,
@@ -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<Crds>,
         filters: &[(CrdsValue, CrdsFilter)],

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
+//! Eager push strategy is based on [Plumtree].
-//! http://asc.di.fct.unl.pt/~jleitao/pdf/srds07-leitao.pdf
+//!
+//! [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<IndexMap<Pubkey, AtomicBloom<Pubkey>>>,
     /// Cursor into the crds table for values to push.
     crds_cursor: Mutex<Cursor>,
     /// 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);

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) {

programs/vote/src/vote_instruction.rs

@@ -57,59 +57,59 @@ pub enum VoteInstruction {
     /// Initialize a vote account
     ///
     /// # Account references
-    ///   0. [WRITE] Uninitialized vote account
+    ///   0. `[WRITE]` Uninitialized vote account
-    ///   1. [] Rent sysvar
+    ///   1. `[]` Rent sysvar
-    ///   2. [] Clock sysvar
+    ///   2. `[]` Clock sysvar
-    ///   3. [SIGNER] New validator identity (node_pubkey)
+    ///   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
+    ///   0. `[WRITE]` Vote account to be updated with the Pubkey for authorization
-    ///   1. [] Clock sysvar
+    ///   1. `[]` Clock sysvar
-    ///   2. [SIGNER] Vote or withdraw authority
+    ///   2. `[SIGNER]` Vote or withdraw authority
     Authorize(Pubkey, VoteAuthorize),
 
     /// A Vote instruction with recent votes
     ///
     /// # Account references
-    ///   0. [WRITE] Vote account to vote with
+    ///   0. `[WRITE]` Vote account to vote with
-    ///   1. [] Slot hashes sysvar
+    ///   1. `[]` Slot hashes sysvar
-    ///   2. [] Clock sysvar
+    ///   2. `[]` Clock sysvar
-    ///   3. [SIGNER] Vote authority
+    ///   3. `[SIGNER]` Vote authority
     Vote(Vote),
 
     /// Withdraw some amount of funds
     ///
     /// # Account references
-    ///   0. [WRITE] Vote account to withdraw from
+    ///   0. `[WRITE]` Vote account to withdraw from
-    ///   1. [WRITE] Recipient account
+    ///   1. `[WRITE]` Recipient account
-    ///   2. [SIGNER] Withdraw authority
+    ///   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
+    ///   0. `[WRITE]` Vote account to be updated with the given authority public key
-    ///   1. [SIGNER] New validator identity (node_pubkey)
+    ///   1. `[SIGNER]` New validator identity (node_pubkey)
-    ///   2. [SIGNER] Withdraw authority
+    ///   2. `[SIGNER]` Withdraw authority
     UpdateValidatorIdentity,
 
     /// Update the commission for the vote account
     ///
     /// # Account references
-    ///   0. [WRITE] Vote account to be updated
+    ///   0. `[WRITE]` Vote account to be updated
-    ///   1. [SIGNER] Withdraw authority
+    ///   1. `[SIGNER]` Withdraw authority
     UpdateCommission(u8),
 
     /// A Vote instruction with recent votes
     ///
     /// # Account references
-    ///   0. [WRITE] Vote account to vote with
+    ///   0. `[WRITE]` Vote account to vote with
-    ///   1. [] Slot hashes sysvar
+    ///   1. `[]` Slot hashes sysvar
-    ///   2. [] Clock sysvar
+    ///   2. `[]` Clock sysvar
-    ///   3. [SIGNER] Vote authority
+    ///   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
+    ///   0. `[WRITE]` Vote account to be updated with the Pubkey for authorization
-    ///   1. [] Clock sysvar
+    ///   1. `[]` Clock sysvar
-    ///   2. [SIGNER] Vote or withdraw authority
+    ///   2. `[SIGNER]` Vote or withdraw authority
-    ///   3. [SIGNER] New vote or withdraw authority
+    ///   3. `[SIGNER]` New vote or withdraw authority
     AuthorizeChecked(VoteAuthorize),
 }
 

runtime/src/append_vec.rs

@@ -1,5 +1,8 @@
-//! Persistent storage for accounts. For more information, see:
+//! Persistent storage for accounts.
-//! https://docs.solana.com/implemented-proposals/persistent-account-storage
+//!
+//! For more information, see:
+//!
+//! <https://docs.solana.com/implemented-proposals/persistent-account-storage>
 
 use log::*;
 use memmap2::MmapMut;

runtime/src/bloom.rs

@@ -67,10 +67,12 @@ impl<T: BloomHashIndex> Bloom<T> {
             _phantom: PhantomData::default(),
         }
     }
-    /// create filter optimal for num size given the `FALSE_RATE`
+    /// 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
+    /// The keys are randomized for picking data out of a collision resistant hash of size
-    /// https://hur.st/bloomfilter/
+    /// `keysize` bytes.
+    ///
+    /// See <https://hur.st/bloomfilter/>.
     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));

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.
+    ///   0. `[writable]` source account to initialize.
-    ///   1. [] Buffer authority, optional, if omitted then the buffer will be
+    ///   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.
+    ///   0. `[writable]` Buffer account to write program data to.
-    ///   1. [signer] Buffer authority
+    ///   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.
+    ///   1. `[writable]` The uninitialized ProgramData account.
-    ///   2. [writable] The uninitialized Program account.
+    ///   2. `[writable]` The uninitialized Program account.
-    ///   3. [writable] The Buffer account where the program data has been
+    ///   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.
+    ///   4. `[]` Rent sysvar.
-    ///   5. [] Clock sysvar.
+    ///   5. `[]` Clock sysvar.
-    ///   6. [] System program (`solana_sdk::system_program::id()`).
+    ///   6. `[]` System program (`solana_sdk::system_program::id()`).
-    ///   7. [signer] The program's authority
+    ///   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.
+    ///   0. `[writable]` The ProgramData account.
-    ///   1. [writable] The Program account.
+    ///   1. `[writable]` The Program account.
-    ///   2. [writable] The Buffer account where the program data has been
+    ///   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.
+    ///   3. `[writable]` The spill account.
-    ///   4. [] Rent sysvar.
+    ///   4. `[]` Rent sysvar.
-    ///   5. [] Clock sysvar.
+    ///   5. `[]` Clock sysvar.
-    ///   6. [signer] The program's authority.
+    ///   6. `[signer]` The program's authority.
     Upgrade,
 
     /// Set a new authority that is allowed to write the buffer or upgrade the

sdk/program/src/program_option.rs

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

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
+    ///   0. `[WRITE]` Uninitialized stake account
-    ///   1. [] Rent sysvar
+    ///   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
+    ///   0. `[WRITE]` Stake account to be updated
-    ///   1. [] Clock sysvar
+    ///   1. `[]` Clock sysvar
-    ///   2. [SIGNER] The stake or withdraw authority
+    ///   2. `[SIGNER]` The stake or withdraw authority
-    ///   3. Optional: [SIGNER] Lockup authority, if updating StakeAuthorize::Withdrawer before
+    ///   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
+    ///   0. `[WRITE]` Initialized stake account to be delegated
-    ///   1. [] Vote account to which this stake will be delegated
+    ///   1. `[]` Vote account to which this stake will be delegated
-    ///   2. [] Clock sysvar
+    ///   2. `[]` Clock sysvar
-    ///   3. [] Stake history sysvar that carries stake warmup/cooldown history
+    ///   3. `[]` Stake history sysvar that carries stake warmup/cooldown history
-    ///   4. [] Address of config account that carries stake config
+    ///   4. `[]` Address of config account that carries stake config
-    ///   5. [SIGNER] Stake authority
+    ///   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
+    ///   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
+    ///   1. `[WRITE]` Uninitialized stake account that will take the split-off amount
-    ///   2. [SIGNER] Stake authority
+    ///   2. `[SIGNER]` Stake authority
     Split(u64),
 
     /// Withdraw unstaked lamports from the stake account
     ///
     /// # Account references
-    ///   0. [WRITE] Stake account from which to withdraw
+    ///   0. `[WRITE]` Stake account from which to withdraw
-    ///   1. [WRITE] Recipient account
+    ///   1. `[WRITE]` Recipient account
-    ///   2. [] Clock sysvar
+    ///   2. `[]` Clock sysvar
-    ///   3. [] Stake history sysvar that carries stake warmup/cooldown history
+    ///   3. `[]` Stake history sysvar that carries stake warmup/cooldown history
-    ///   4. [SIGNER] Withdraw authority
+    ///   4. `[SIGNER]` Withdraw authority
-    ///   5. Optional: [SIGNER] Lockup authority, if before lockup expiration
+    ///   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
+    ///   0. `[WRITE]` Delegated stake account
-    ///   1. [] Clock sysvar
+    ///   1. `[]` Clock sysvar
-    ///   2. [SIGNER] Stake authority
+    ///   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
+    ///   0. `[WRITE]` Initialized stake account
-    ///   1. [SIGNER] Lockup authority or withdraw authority
+    ///   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
+    ///   0. `[WRITE]` Destination stake account for the merge
-    ///   1. [WRITE] Source stake account for to merge.  This account will be drained
+    ///   1. `[WRITE]` Source stake account for to merge.  This account will be drained
-    ///   2. [] Clock sysvar
+    ///   2. `[]` Clock sysvar
-    ///   3. [] Stake history sysvar that carries stake warmup/cooldown history
+    ///   3. `[]` Stake history sysvar that carries stake warmup/cooldown history
-    ///   4. [SIGNER] Stake authority
+    ///   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
+    ///   0. `[WRITE]` Stake account to be updated
-    ///   1. [SIGNER] Base key of stake or withdraw authority
+    ///   1. `[SIGNER]` Base key of stake or withdraw authority
-    ///   2. [] Clock sysvar
+    ///   2. `[]` Clock sysvar
-    ///   3. Optional: [SIGNER] Lockup authority, if updating StakeAuthorize::Withdrawer before
+    ///   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
+    ///   0. `[WRITE]` Uninitialized stake account
-    ///   1. [] Rent sysvar
+    ///   1. `[]` Rent sysvar
-    ///   2. [] The stake authority
+    ///   2. `[]` The stake authority
-    ///   3. [SIGNER] The withdraw 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
+    ///   0. `[WRITE]` Stake account to be updated
-    ///   1. [] Clock sysvar
+    ///   1. `[]` Clock sysvar
-    ///   2. [SIGNER] The stake or withdraw authority
+    ///   2. `[SIGNER]` The stake or withdraw authority
-    ///   3. [SIGNER] The new stake or withdraw authority
+    ///   3. `[SIGNER]` The new stake or withdraw authority
-    ///   4. Optional: [SIGNER] Lockup authority, if updating StakeAuthorize::Withdrawer before
+    ///   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
+    ///   0. `[WRITE]` Stake account to be updated
-    ///   1. [SIGNER] Base key of stake or withdraw authority
+    ///   1. `[SIGNER]` Base key of stake or withdraw authority
-    ///   2. [] Clock sysvar
+    ///   2. `[]` Clock sysvar
-    ///   3. [SIGNER] The new stake or withdraw authority
+    ///   3. `[SIGNER]` The new stake or withdraw authority
-    ///   4. Optional: [SIGNER] Lockup authority, if updating StakeAuthorize::Withdrawer before
+    ///   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
+    ///   0. `[WRITE]` Initialized stake account
-    ///   1. [SIGNER] Lockup authority or withdraw authority
+    ///   1. `[SIGNER]` Lockup authority or withdraw authority
-    ///   2. Optional: [SIGNER] New lockup authority
+    ///   2. Optional: `[SIGNER]` New lockup authority
     SetLockupChecked(LockupCheckedArgs),
 }
 

sdk/program/src/system_instruction.rs

@@ -58,8 +58,8 @@ pub enum SystemInstruction {
     /// Create a new account
     ///
     /// # Account references
-    ///   0. [WRITE, SIGNER] Funding account
+    ///   0. `[WRITE, SIGNER]` Funding account
-    ///   1. [WRITE, SIGNER] New 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
+    ///   0. `[WRITE, SIGNER]` Funding account
-    ///   1. [WRITE] Recipient 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
+    ///   0. `[WRITE, SIGNER]` Funding account
-    ///   1. [WRITE] Created account
+    ///   1. `[WRITE]` Created account
-    ///   2. [SIGNER] (optional) Base account; the account matching the base Pubkey below must be
+    ///   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
+    ///   0. `[WRITE]` Nonce account
-    ///   1. [] RecentBlockhashes sysvar
+    ///   1. `[]` RecentBlockhashes sysvar
-    ///   2. [SIGNER] Nonce authority
+    ///   2. `[SIGNER]` Nonce authority
     AdvanceNonceAccount,
 
     /// Withdraw funds from a nonce account
     ///
     /// # Account references
-    ///   0. [WRITE] Nonce account
+    ///   0. `[WRITE]` Nonce account
-    ///   1. [WRITE] Recipient account
+    ///   1. `[WRITE]` Recipient account
-    ///   2. [] RecentBlockhashes sysvar
+    ///   2. `[]` RecentBlockhashes sysvar
-    ///   3. [] Rent sysvar
+    ///   3. `[]` Rent sysvar
-    ///   4. [SIGNER] Nonce authority
+    ///   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
+    ///   0. `[WRITE]` Nonce account
-    ///   1. [] RecentBlockhashes sysvar
+    ///   1. `[]` RecentBlockhashes sysvar
-    ///   2. [] Rent 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
+    ///   0. `[WRITE]` Nonce account
-    ///   1. [SIGNER] Nonce authority
+    ///   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
+    ///   0. `[WRITE]` Allocated account
-    ///   1. [SIGNER] Base 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
+    ///   0. `[WRITE]` Assigned account
-    ///   1. [SIGNER] Base 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
+    ///   0. `[WRITE]` Funding account
-    ///   1. [SIGNER] Base for funding account
+    ///   1. `[SIGNER]` Base for funding account
-    ///   2. [WRITE] Recipient account
+    ///   2. `[WRITE]` Recipient account
     TransferWithSeed {
         /// Amount to transfer
         lamports: u64,

sdk/src/process_instruction.rs

@@ -243,7 +243,10 @@ pub mod stable_log {
     /// Log a program invoke.
     ///
     /// The general form is:
-    ///     "Program <address> invoke [<depth>]"
+    ///
+    /// ```notrust
+    /// "Program <address> invoke [<depth>]"
+    /// ```
     pub fn program_invoke(
         logger: &Rc<RefCell<dyn Logger>>,
         program_id: &Pubkey,
@@ -255,7 +258,11 @@ pub mod stable_log {
     /// Log a message from the program itself.
     ///
     /// The general form is:
-    ///     "Program log: <program-generated output>"
+    ///
+    /// ```notrust
+    /// "Program log: <program-generated output>"
+    /// ```
+    ///
     /// That is, any program-generated output is guaranteed to be prefixed by "Program log: "
     pub fn program_log(logger: &Rc<RefCell<dyn Logger>>, 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 <address> success"
+    ///
+    /// ```notrust
+    /// "Program <address> success"
+    /// ```
     pub fn program_success(logger: &Rc<RefCell<dyn Logger>>, 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 <address> failed: <program error details>"
+    ///
+    /// ```notrust
+    /// "Program <address> failed: <program error details>"
+    /// ```
     pub fn program_failure(
         logger: &Rc<RefCell<dyn Logger>>,
         program_id: &Pubkey,