[docs] Cleanup Rust doc warnings before we add Github checks for Rust…

…doc (aptos-labs#7367)

* [docs] Cleanup doc warnings across codebase

* [docs] Update framework to fix Rust doc warnings

* [docs] Update aptos protos to fix Rust doc warnings

* [docs] Update move to fix rust doc warnings

api/src/response.rs

@@ -4,7 +4,7 @@
 //! The Aptos API response / error handling philosophy.
 //!
 //! The return type for every endpoint should be a
-//! poem::Result<MyResponse<T>, MyError> where MyResponse is an instance of
+//! `poem::Result<MyResponse<T>, MyError>` where MyResponse is an instance of
 //! ApiResponse that contains only the status codes that it can actually
 //! return. This will manifest in the OpenAPI spec, making it clear to users
 //! what the API can actually return. The error should operate the same way,

api/types/src/derives.rs

@@ -11,7 +11,7 @@
 //! serialize them as strings, e.g. EntryFunctionId.
 //!
 //! For potential future improvements here, see:
-//! https://github.com/aptos-labs/aptos-core/issues/2319.
+//! <https://github.com/aptos-labs/aptos-core/issues/2319>
 
 // READ ME: You'll see that some of the examples (specifically those for hex
 // strings) have a space at the end. This is necessary to make sure the UI

aptos-move/e2e-tests/src/account.rs

@@ -89,8 +89,8 @@ impl Account {
 
     /// Creates a new account in memory representing an account created in the genesis transaction.
     ///
-    /// The address will be [`address`], which should be an address for a genesis account and
-    /// the account will use [`GENESIS_KEYPAIR`][struct@GENESIS_KEYPAIR] as its keypair.
+    /// The address will be `address`, which should be an address for a genesis account and
+    /// the account will use [`GENESIS_KEYPAIR`][static@@GENESIS_KEYPAIR] as its keypair.
     pub fn new_genesis_account(address: AccountAddress) -> Self {
         Account {
             addr: address,
@@ -102,7 +102,7 @@ impl Account {
     /// Creates a new account representing the aptos root account in memory.
     ///
     /// The address will be [`aptos_test_root_address`][account_config::aptos_test_root_address], and
-    /// the account will use [`GENESIS_KEYPAIR`][struct@GENESIS_KEYPAIR] as its keypair.
+    /// the account will use [`GENESIS_KEYPAIR`][static@GENESIS_KEYPAIR] as its keypair.
     pub fn new_aptos_root() -> Self {
         Self::new_genesis_account(account_config::aptos_test_root_address())
     }

aptos-move/e2e-tests/src/account_universe/universe.rs

@@ -18,7 +18,7 @@ use proptest_derive::Arbitrary;
 
 /// A set of accounts which can be used to construct an initial state.
 ///
-/// For more, see the [`account_universe` module documentation][self].
+/// For more, see the [`account_universe` module documentation].
 #[derive(Clone, Debug)]
 pub struct AccountUniverseGen {
     accounts: Vec<AccountData>,
@@ -27,7 +27,7 @@ pub struct AccountUniverseGen {
 
 /// A set of accounts that has been set up and can now be used to conduct transactions on.
 ///
-/// For more, see the [`account_universe` module documentation][self].
+/// For more, see the [`account_universe` module documentation].
 #[derive(Clone, Debug)]
 pub struct AccountUniverse {
     accounts: Vec<AccountCurrent>,

aptos-move/e2e-tests/src/data_store.rs

@@ -35,7 +35,7 @@ pub static GENESIS_CHANGE_SET_TESTNET: Lazy<ChangeSet> =
 pub static GENESIS_CHANGE_SET_MAINNET: Lazy<ChangeSet> =
     Lazy::new(|| generate_genesis_change_set_for_mainnet(GenesisOptions::Mainnet));
 
-/// An in-memory implementation of [`StateView`] and [`RemoteCache`] for the VM.
+/// An in-memory implementation of `StateView` and `RemoteCache` for the VM.
 ///
 /// Tests use this to set up state, and pass in a reference to the cache whenever a `StateView` or
 /// `RemoteCache` is needed.
@@ -94,7 +94,7 @@ impl FakeDataStore {
         self.add_write_set(&write_set)
     }
 
-    /// Adds a [`CompiledModule`] to this data store.
+    /// Adds a `CompiledModule` to this data store.
     ///
     /// Does not do any sort of verification on the module.
     pub fn add_module(&mut self, module_id: &ModuleId, blob: Vec<u8>) {

aptos-move/e2e-tests/src/executor.rs

@@ -285,7 +285,7 @@ impl FakeExecutor {
         self.data_store.add_module(module_id, module_blob)
     }
 
-    /// Reads the resource [`Value`] for an account from this executor's data store.
+    /// Reads the resource `Value` for an account from this executor's data store.
     pub fn read_account_resource(&self, account: &Account) -> Option<AccountResource> {
         self.read_account_resource_at_address(account.address())
     }
@@ -300,7 +300,7 @@ impl FakeExecutor {
         bcs::from_bytes(data_blob.as_slice()).ok()
     }
 
-    /// Reads the resource [`Value`] for an account under the given address from
+    /// Reads the resource `Value` for an account under the given address from
     /// this executor's data store.
     pub fn read_account_resource_at_address(
         &self,

aptos-move/framework/aptos-framework/doc/account.md

@@ -1100,25 +1100,25 @@ To authorize the rotation, we need two signatures:
 demonstrating that the user intends to and has the capability to rotate the authentication key of this account;
 - the second signature <code>cap_update_table</code> refers to the signature by the new key (that the account owner wants to rotate to) on a
 valid <code><a href="account.md#0x1_account_RotationProofChallenge">RotationProofChallenge</a></code>, demonstrating that the user owns the new private key, and has the authority to update the
-<code><a href="account.md#0x1_account_OriginatingAddress">OriginatingAddress</a></code> map with the new address mapping <new_address, originating_address>.
+<code><a href="account.md#0x1_account_OriginatingAddress">OriginatingAddress</a></code> map with the new address mapping <code>&lt;new_address, originating_address&gt;</code>.
 To verify these two signatures, we need their corresponding public key and public key scheme: we use <code>from_scheme</code> and <code>from_public_key_bytes</code>
 to verify <code>cap_rotate_key</code>, and <code>to_scheme</code> and <code>to_public_key_bytes</code> to verify <code>cap_update_table</code>.
 A scheme of 0 refers to an Ed25519 key and a scheme of 1 refers to Multi-Ed25519 keys.
 <code>originating <b>address</b></code> refers to an account's original/first address.
 
 Here is an example attack if we don't ask for the second signature <code>cap_update_table</code>:
-Alice has rotated her account addr_a to new_addr_a. As a result, the following entry is created, to help Alice when recovering her wallet:
-OriginatingAddress[new_addr_a] -> addr_a
+Alice has rotated her account <code>addr_a</code> to <code>new_addr_a</code>. As a result, the following entry is created, to help Alice when recovering her wallet:
+<code><a href="account.md#0x1_account_OriginatingAddress">OriginatingAddress</a>[new_addr_a]</code> -> <code>addr_a</code>
 Alice has had bad day: her laptop blew up and she needs to reset her account on a new one.
-(Fortunately, she still has her secret key new_sk_a associated with her new address new_addr_a, so she can do this.)
+(Fortunately, she still has her secret key <code>new_sk_a</code> associated with her new address <code>new_addr_a</code>, so she can do this.)
 
 But Bob likes to mess with Alice.
-Bob creates an account addr_b and maliciously rotates it to Alice's new address new_addr_a. Since we are no longer checking a PoK,
+Bob creates an account <code>addr_b</code> and maliciously rotates it to Alice's new address <code>new_addr_a</code>. Since we are no longer checking a PoK,
 Bob can easily do this.
 
-Now, the table will be updated to make Alice's new address point to Bob's address: OriginatingAddress[new_addr_a] -> addr_b.
-When Alice recovers her account, her wallet will display the attacker's address (Bob's) addr_b as her address.
-Now Alice will give addr_b to everyone to pay her, but the money will go to Bob.
+Now, the table will be updated to make Alice's new address point to Bob's address: <code><a href="account.md#0x1_account_OriginatingAddress">OriginatingAddress</a>[new_addr_a]</code> -> <code>addr_b</code>.
+When Alice recovers her account, her wallet will display the attacker's address (Bob's) <code>addr_b</code> as her address.
+Now Alice will give <code>addr_b</code> to everyone to pay her, but the money will go to Bob.
 
 Because we ask for a valid <code>cap_update_table</code>, this kind of attack is not possible. Bob would not have the secret key of Alice's address
 to rotate his address to Alice's address in the first place.

aptos-move/framework/aptos-framework/doc/resource_account.md

@@ -208,7 +208,7 @@ Creates a new resource account, transfer the amount of coins from the origin to
 account, and rotates the authentication key to either the optional auth key if it is
 non-empty (though auth keys are 32-bytes) or the source accounts current auth key. Note,
 this function adds additional resource ownership to the resource account and should only be
-used for resource accounts that need access to Coin<AptosCoin>.
+used for resource accounts that need access to <code>Coin&lt;AptosCoin&gt;</code>.
 
 
 <pre><code><b>public</b> entry <b>fun</b> <a href="resource_account.md#0x1_resource_account_create_resource_account_and_fund">create_resource_account_and_fund</a>(origin: &<a href="../../aptos-stdlib/../move-stdlib/doc/signer.md#0x1_signer">signer</a>, seed: <a href="../../aptos-stdlib/../move-stdlib/doc/vector.md#0x1_vector">vector</a>&lt;u8&gt;, optional_auth_key: <a href="../../aptos-stdlib/../move-stdlib/doc/vector.md#0x1_vector">vector</a>&lt;u8&gt;, fund_amount: u64)

aptos-move/framework/aptos-framework/sources/account.move

@@ -270,25 +270,25 @@ module aptos_framework::account {
     /// demonstrating that the user intends to and has the capability to rotate the authentication key of this account;
     /// - the second signature `cap_update_table` refers to the signature by the new key (that the account owner wants to rotate to) on a
     /// valid `RotationProofChallenge`, demonstrating that the user owns the new private key, and has the authority to update the
-    /// `OriginatingAddress` map with the new address mapping <new_address, originating_address>.
+    /// `OriginatingAddress` map with the new address mapping `<new_address, originating_address>`.
     /// To verify these two signatures, we need their corresponding public key and public key scheme: we use `from_scheme` and `from_public_key_bytes`
     /// to verify `cap_rotate_key`, and `to_scheme` and `to_public_key_bytes` to verify `cap_update_table`.
     /// A scheme of 0 refers to an Ed25519 key and a scheme of 1 refers to Multi-Ed25519 keys.
     /// `originating address` refers to an account's original/first address.
     ///
     /// Here is an example attack if we don't ask for the second signature `cap_update_table`:
-    /// Alice has rotated her account addr_a to new_addr_a. As a result, the following entry is created, to help Alice when recovering her wallet:
-    /// OriginatingAddress[new_addr_a] -> addr_a
+    /// Alice has rotated her account `addr_a` to `new_addr_a`. As a result, the following entry is created, to help Alice when recovering her wallet:
+    /// `OriginatingAddress[new_addr_a]` -> `addr_a`
     /// Alice has had bad day: her laptop blew up and she needs to reset her account on a new one.
-    /// (Fortunately, she still has her secret key new_sk_a associated with her new address new_addr_a, so she can do this.)
+    /// (Fortunately, she still has her secret key `new_sk_a` associated with her new address `new_addr_a`, so she can do this.)
     ///
     /// But Bob likes to mess with Alice.
-    /// Bob creates an account addr_b and maliciously rotates it to Alice's new address new_addr_a. Since we are no longer checking a PoK,
+    /// Bob creates an account `addr_b` and maliciously rotates it to Alice's new address `new_addr_a`. Since we are no longer checking a PoK,
     /// Bob can easily do this.
     ///
-    /// Now, the table will be updated to make Alice's new address point to Bob's address: OriginatingAddress[new_addr_a] -> addr_b.
-    /// When Alice recovers her account, her wallet will display the attacker's address (Bob's) addr_b as her address.
-    /// Now Alice will give addr_b to everyone to pay her, but the money will go to Bob.
+    /// Now, the table will be updated to make Alice's new address point to Bob's address: `OriginatingAddress[new_addr_a]` -> `addr_b`.
+    /// When Alice recovers her account, her wallet will display the attacker's address (Bob's) `addr_b` as her address.
+    /// Now Alice will give `addr_b` to everyone to pay her, but the money will go to Bob.
     ///
     /// Because we ask for a valid `cap_update_table`, this kind of attack is not possible. Bob would not have the secret key of Alice's address
     /// to rotate his address to Alice's address in the first place.

aptos-move/framework/aptos-framework/sources/resource_account.move

@@ -99,7 +99,7 @@ module aptos_framework::resource_account {
     /// account, and rotates the authentication key to either the optional auth key if it is
     /// non-empty (though auth keys are 32-bytes) or the source accounts current auth key. Note,
     /// this function adds additional resource ownership to the resource account and should only be
-    /// used for resource accounts that need access to Coin<AptosCoin>.
+    /// used for resource accounts that need access to `Coin<AptosCoin>`.
     public entry fun create_resource_account_and_fund(
         origin: &signer,
         seed: vector<u8>,