Fix docs (#7710)

* fix docs

* Update frame/merkle-mountain-range/src/lib.rs

Co-authored-by: Alexander Theißen <alex.theissen@me.com>

Co-authored-by: Alexander Theißen <alex.theissen@me.com>

substrate/bin/node/browser-testing/src/lib.rs

@@ -26,7 +26,7 @@
 //! ```
 //! For debug infomation, such as the informant, run without the `--headless`
 //! flag and open a browser to the url that `wasm-pack test` outputs.
-//! For more infomation see https://rustwasm.github.io/docs/wasm-pack/.
+//! For more infomation see <https://rustwasm.github.io/docs/wasm-pack/>.
 
 use wasm_bindgen_test::{wasm_bindgen_test, wasm_bindgen_test_configure};
 use wasm_bindgen_futures::JsFuture;

substrate/bin/node/runtime/src/lib.rs

@@ -16,7 +16,7 @@
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-//! The Substrate runtime. This can be compiled with ``#[no_std]`, ready for Wasm.
+//! The Substrate runtime. This can be compiled with `#[no_std]`, ready for Wasm.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 // `construct_runtime!` does a lot of recursion and requires us to increase the limit to 256.

substrate/client/authority-discovery/src/service.rs

@@ -22,14 +22,14 @@ use futures::SinkExt;
 use sc_network::{Multiaddr, PeerId};
 use sp_authority_discovery::AuthorityId;
 
-/// Service to interact with the [`Worker`].
+/// Service to interact with the [`crate::Worker`].
 #[derive(Clone)]
 pub struct Service {
 	to_worker: mpsc::Sender<ServicetoWorkerMsg>,
 }
 
-/// A [`Service`] allows to interact with a [`Worker`], e.g. by querying the
-/// [`Worker`]'s local address cache for a given [`AuthorityId`].
+/// A [`Service`] allows to interact with a [`crate::Worker`], e.g. by querying the
+/// [`crate::Worker`]'s local address cache for a given [`AuthorityId`].
 impl Service {
 	pub(crate) fn new(to_worker: mpsc::Sender<ServicetoWorkerMsg>) -> Self {
 		Self {
@@ -44,7 +44,7 @@ impl Service {
 	/// [`crate::Worker`] failed.
 	///
 	/// Note: [`Multiaddr`]s returned always include a [`PeerId`] via a
-	/// [`libp2p::core::multiaddr:Protocol::P2p`] component. Equality of
+	/// [`libp2p::core::multiaddr::Protocol::P2p`] component. Equality of
 	/// [`PeerId`]s across [`Multiaddr`]s returned by a single call is not
 	/// enforced today, given that there are still authorities out there
 	/// publishing the addresses of their sentry nodes on the DHT. In the future

substrate/client/authority-discovery/src/worker.rs

@@ -100,7 +100,7 @@ pub enum Role {
 ///
 ///    5. Allow querying of the collected addresses via the [`crate::Service`].
 pub struct Worker<Client, Network, Block, DhtEventStream> {
-	/// Channel receiver for messages send by a [`Service`].
+	/// Channel receiver for messages send by a [`crate::Service`].
 	from_service: Fuse<mpsc::Receiver<ServicetoWorkerMsg>>,
 
 	client: Arc<Client>,
@@ -615,8 +615,8 @@ where
 }
 
 /// NetworkProvider provides [`Worker`] with all necessary hooks into the
-/// underlying Substrate networking. Using this trait abstraction instead of [`NetworkService`]
-/// directly is necessary to unit test [`Worker`].
+/// underlying Substrate networking. Using this trait abstraction instead of
+/// [`sc_network::NetworkService`] directly is necessary to unit test [`Worker`].
 #[async_trait]
 pub trait NetworkProvider: NetworkStateInfo {
 	/// Modify a peerset priority group.

substrate/client/basic-authorship/src/basic_authorship.rs

@@ -44,7 +44,7 @@ use sc_proposer_metrics::MetricsLink as PrometheusMetrics;
 
 /// Default maximum block size in bytes used by [`Proposer`].
 ///
-/// Can be overwritten by [`ProposerFactory::set_maxium_block_size`].
+/// Can be overwritten by [`ProposerFactory::set_maximum_block_size`].
 ///
 /// Be aware that there is also an upper packet size on what the networking code
 /// will accept. If the block doesn't fit in such a package, it can not be

substrate/client/basic-authorship/src/lib.rs

@@ -71,4 +71,4 @@
 
 mod basic_authorship;
 
-pub use crate::basic_authorship::{ProposerFactory, Proposer};
+pub use crate::basic_authorship::{ProposerFactory, Proposer, DEFAULT_MAX_BLOCK_SIZE};

substrate/client/cli/src/commands/run_cmd.rs

@@ -75,7 +75,8 @@ pub struct RunCmd {
 	/// Listen to all RPC interfaces.
 	///
 	/// Default is local. Note: not all RPC methods are safe to be exposed publicly. Use an RPC proxy
-	/// server to filter out dangerous methods. More details: https://github.com/paritytech/substrate/wiki/Public-RPC.
+	/// server to filter out dangerous methods. More details:
+	/// <https://github.com/paritytech/substrate/wiki/Public-RPC>.
 	/// Use `--unsafe-rpc-external` to suppress the warning if you understand the risks.
 	#[structopt(long = "rpc-external")]
 	pub rpc_external: bool,
@@ -105,7 +106,7 @@ pub struct RunCmd {
 	/// Listen to all Websocket interfaces.
 	///
 	/// Default is local. Note: not all RPC methods are safe to be exposed publicly. Use an RPC proxy
-	/// server to filter out dangerous methods. More details: https://github.com/paritytech/substrate/wiki/Public-RPC.
+	/// server to filter out dangerous methods. More details: <https://github.com/paritytech/substrate/wiki/Public-RPC>.
 	/// Use `--unsafe-ws-external` to suppress the warning if you understand the risks.
 	#[structopt(long = "ws-external")]
 	pub ws_external: bool,
@@ -142,7 +143,7 @@ pub struct RunCmd {
 	///
 	/// A comma-separated list of origins (protocol://domain or special `null`
 	/// value). Value of `all` will disable origin validation. Default is to
-	/// allow localhost and https://polkadot.js.org origins. When running in
+	/// allow localhost and <https://polkadot.js.org> origins. When running in
 	/// --dev mode the default is to allow all origins.
 	#[structopt(long = "rpc-cors", value_name = "ORIGINS", parse(try_from_str = parse_cors))]
 	pub rpc_cors: Option<Cors>,

substrate/client/cli/src/commands/utils.rs

@@ -57,7 +57,7 @@ pub fn read_uri(uri: Option<&String>) -> error::Result<String> {
 /// 2. Try to construct the `Pair` while using `uri` as input for [`sp_core::Pair::from_string_with_seed`].
 ///
 /// 3. Try to construct the `Pair::Public` while using `uri` as input for
-///    [`sp_core::Pair::Public::from_string_with_version`].
+///    [`sp_core::crypto::Ss58Codec::from_string_with_version`].
 pub fn print_from_uri<Pair>(
 	uri: &str,
 	password: Option<SecretString>,

substrate/client/cli/src/config.rs

@@ -47,7 +47,7 @@ const RECOMMENDED_OPEN_FILE_DESCRIPTOR_LIMIT: u64 = 10_000;
 
 /// Default configuration values used by Substrate
 ///
-/// These values will be used by [`CliConfiguritation`] to set
+/// These values will be used by [`CliConfiguration`] to set
 /// default values for e.g. the listen port or the RPC port.
 pub trait DefaultConfigurationValues {
 	/// The port Substrate should listen on for p2p connections.

substrate/client/finality-grandpa/src/lib.rs

@@ -329,7 +329,7 @@ impl<Block: BlockT, Client> BlockStatus<Block> for Arc<Client> where
 
 /// A trait that includes all the client functionalities grandpa requires.
 /// Ideally this would be a trait alias, we're not there yet.
-/// tracking issue https://github.com/rust-lang/rust/issues/41517
+/// tracking issue <https://github.com/rust-lang/rust/issues/41517>
 pub trait ClientForGrandpa<Block, BE>:
 	LockImportRun<Block, BE> + Finalizer<Block, BE> + AuxStore
 	+ HeaderMetadata<Block, Error = sp_blockchain::Error> + HeaderBackend<Block>

substrate/client/network/src/gossip.rs

@@ -41,7 +41,7 @@
 //! In normal situations, messages sent through a [`QueuedSender`] will arrive in the same
 //! order as they have been sent.
 //! It is possible, in the situation of disconnects and reconnects, that messages arrive in a
-//! different order. See also https://github.com/paritytech/substrate/issues/6756.
+//! different order. See also <https://github.com/paritytech/substrate/issues/6756>.
 //! However, if multiple instances of [`QueuedSender`] exist for the same peer and protocol, or
 //! if some other code uses the [`NetworkService`] to send notifications to this combination or
 //! peer and protocol, then the notifications will be interleaved in an unpredictable way.

substrate/client/service/src/client/mod.rs

@@ -23,22 +23,23 @@
 //!
 //! - A database containing the blocks and chain state, generally referred to as
 //! the [`Backend`](sc_client_api::backend::Backend).
-//! - A runtime environment, generally referred to as the [`Executor`](CallExecutor).
+//! - A runtime environment, generally referred to as the
+//! [`Executor`](sc_client_api::call_executor::CallExecutor).
 //!
 //! # Initialization
 //!
 //! Creating a [`Client`] is done by calling the `new` method and passing to it a
-//! [`Backend`](sc_client_api::backend::Backend) and an [`Executor`](CallExecutor).
+//! [`Backend`](sc_client_api::backend::Backend) and an
+//! [`Executor`](sc_client_api::call_executor::CallExecutor).
 //!
 //! The former is typically provided by the `sc-client-db` crate.
 //!
 //! The latter typically requires passing one of:
 //!
 //! - A [`LocalCallExecutor`] running the runtime locally.
-//! - A [`RemoteCallExecutor`](light::call_executor::RemoteCallRequest) that will ask a
+//! - A [`RemoteCallExecutor`](sc_client_api::light::RemoteCallRequest) that will ask a
 //! third-party to perform the executions.
-//! - A [`RemoteOrLocalCallExecutor`](light::call_executor::RemoteOrLocalCallExecutor), combination
-//! of the two.
+//! - A [`RemoteOrLocalCallExecutor`](sc_client_api::light::LocalOrRemote), combination of the two.
 //!
 //! Additionally, the fourth generic parameter of the `Client` is a marker type representing
 //! the ways in which the runtime can interface with the outside. Any code that builds a `Client`

substrate/client/telemetry/src/async_record.rs

@@ -1,6 +1,6 @@
 //! # Internal types to ssync drain slog
 //! FIXME: REMOVE THIS ONCE THE PR WAS MERGE
-//! https://github.com/slog-rs/async/pull/14
+//! <https://github.com/slog-rs/async/pull/14>
 
 use slog::{Record, RecordStatic, Level, SingleKV, KV, BorrowedKV};
 use slog::{Serializer, OwnedKVList, Key};

substrate/frame/contracts/src/schedule.rs

@@ -69,7 +69,7 @@ pub struct Limits {
 
 	/// Maximum allowed stack height in number of elements.
 	///
-	/// See https://wiki.parity.io/WebAssembly-StackHeight to find out
+	/// See <https://wiki.parity.io/WebAssembly-StackHeight> to find out
 	/// how the stack frame cost is calculated. Each element can be of one of the
 	/// wasm value types. This means the maximum size per element is 64bit.
 	pub stack_height: u32,

substrate/frame/example/src/lib.rs

@@ -131,7 +131,7 @@
 //! <!-- Original author of paragraph: ??? -->
 //!
 //! // Reference documentation of aspects such as `storageItems` and `dispatchable` functions should only be
-//! // included in the https://docs.rs Rustdocs for Substrate and not repeated in the README file.
+//! // included in the <https://docs.rs> Rustdocs for Substrate and not repeated in the README file.
 //!
 //! \### Dispatchable Functions
 //!
@@ -224,8 +224,8 @@
 //! // Show a usage example in an actual runtime
 //!
 //! // See:
-//! // - Substrate TCR https://github.com/parity-samples/substrate-tcr
-//! // - Substrate Kitties https://shawntabrizi.github.io/substrate-collectables-workshop/#/
+//! // - Substrate TCR <https://github.com/parity-samples/substrate-tcr>
+//! // - Substrate Kitties <https://shawntabrizi.github.io/substrate-collectables-workshop/#/>
 //!
 //! \## Genesis Config
 //!

substrate/frame/merkle-mountain-range/src/lib.rs

@@ -20,7 +20,7 @@
 //! ## Overview
 //!
 //! Details on Merkle Mountain Ranges (MMRs) can be found here:
-//! https://github.com/mimblewimble/grin/blob/master/doc/mmr.md
+//! <https://github.com/mimblewimble/grin/blob/master/doc/mmr.md>
 //!
 //! The MMR pallet constructs a MMR from leaf data obtained on every block from
 //! `LeafDataProvider`. MMR nodes are stored both in:
@@ -41,7 +41,7 @@
 //! ## What for?
 //!
 //!	Primary use case for this pallet is to generate MMR root hashes, that can latter on be used by
-//!	BEEFY protocol (see https://github.com/paritytech/grandpa-bridge-gadget).
+//!	BEEFY protocol (see <https://github.com/paritytech/grandpa-bridge-gadget>).
 //!	MMR root hashes along with BEEFY will make it possible to build Super Light Clients (SLC) of
 //!	Substrate-based chains. The SLC will be able to follow finality and can be shown proofs of more
 //!	details that happened on the source chain.
@@ -88,7 +88,7 @@ pub trait Config<I = DefaultInstance>: frame_system::Config {
 	/// and some of the inner mmr nodes might be pruned from on-chain storage.
 	/// The later will contain all the entries in their full form.
 	///
-	/// Each node is stored in the Off-chain DB under key derived from the [INDEXING_PREFIX] and
+	/// Each node is stored in the Off-chain DB under key derived from the [`Self::INDEXING_PREFIX`] and
 	/// it's in-tree index (MMR position).
 	const INDEXING_PREFIX: &'static [u8];
 

substrate/frame/proxy/src/lib.rs

@@ -706,7 +706,7 @@ impl<T: Config> Module<T> {
 pub mod migration {
 	use super::*;
 
-	/// Migration code for https://github.com/paritytech/substrate/pull/6770
+	/// Migration code for <https://github.com/paritytech/substrate/pull/6770>
 	///
 	/// Details: This migration was introduced between Substrate 2.0-RC6 and Substrate 2.0 releases.
 	/// Before this migration, the `Proxies` storage item used a tuple of `AccountId` and

substrate/frame/session/src/historical/onchain.rs

@@ -55,7 +55,7 @@ pub fn store_session_validator_set_to_offchain<T: HistoricalConfig + SessionConf
 
 /// Store the validator set associated to the _current_ session index to the off-chain database.
 ///
-/// See [`fn store_session_validator_set_...(..)`](Self::store_session_validator_set_to_offchain)
+/// See [`store_session_validator_set_to_offchain`]
 /// for further information and restrictions.
 pub fn store_current_session_validator_set_to_offchain<T: HistoricalConfig + SessionConfig>() {
 	store_session_validator_set_to_offchain::<T>(<SessionModule<T>>::current_index());

substrate/frame/staking/src/lib.rs

@@ -2166,7 +2166,7 @@ impl<T: Config> Module<T> {
 		Self::bonded(stash).and_then(Self::ledger).map(|l| l.active).unwrap_or_default()
 	}
 
-	/// Internal impl of [`slashable_balance_of`] that returns [`VoteWeight`].
+	/// Internal impl of [`Self::slashable_balance_of`] that returns [`VoteWeight`].
 	pub fn slashable_balance_of_vote_weight(stash: &T::AccountId, issuance: BalanceOf<T>) -> VoteWeight {
 		T::CurrencyToVote::to_vote(Self::slashable_balance_of(stash), issuance)
 	}
@@ -2833,7 +2833,7 @@ impl<T: Config> Module<T> {
 	/// Execute election and return the new results. The edge weights are processed into support
 	/// values.
 	///
-	/// This is basically a wrapper around [`do_phragmen`] which translates
+	/// This is basically a wrapper around [`Self::do_phragmen`] which translates
 	/// `PrimitiveElectionResult` into `ElectionResult`.
 	///
 	/// No storage item is updated.

substrate/frame/staking/src/slashing.rs

@@ -47,7 +47,7 @@
 //! has multiple misbehaviors. However, accounting for such cases is necessary
 //! to deter a class of "rage-quit" attacks.
 //!
-//! Based on research at https://research.web3.foundation/en/latest/polkadot/slashing/npos/
+//! Based on research at <https://research.web3.foundation/en/latest/polkadot/slashing/npos/>
 
 use super::{
 	EraIndex, Config, Module, Store, BalanceOf, Exposure, Perbill, SessionInterface,

substrate/frame/support/src/traits.rs

@@ -1901,7 +1901,7 @@ impl PalletVersion {
 
 	/// Returns the storage key for a pallet version.
 	///
-	/// See [`PALLET_VERSION_STORAGE_KEY_POSTIFX`] on how this key is built.
+	/// See [`PALLET_VERSION_STORAGE_KEY_POSTFIX`] on how this key is built.
 	///
 	/// Returns `None` if the given `PI` returned a `None` as name for the given
 	/// `Pallet`.

substrate/frame/transaction-payment/src/lib.rs

@@ -109,7 +109,7 @@ type BalanceOf<T> =
 /// Meaning that fees can change by around ~23% per day, given extreme congestion.
 ///
 /// More info can be found at:
-/// https://w3f-research.readthedocs.io/en/latest/polkadot/Token%20Economics.html
+/// <https://w3f-research.readthedocs.io/en/latest/polkadot/Token%20Economics.html>
 pub struct TargetedFeeAdjustment<T, S, V, M>(sp_std::marker::PhantomData<(T, S, V, M)>);
 
 /// Something that can convert the current multiplier to the next one.

substrate/frame/treasury/src/lib.rs

@@ -414,19 +414,19 @@ decl_event!(
 		TipClosed(Hash, AccountId, Balance),
 		/// A tip suggestion has been retracted. \[tip_hash\]
 		TipRetracted(Hash),
-		/// New bounty proposal. [index]
+		/// New bounty proposal. \[index\]
 		BountyProposed(BountyIndex),
 		/// A bounty proposal was rejected; funds were slashed. [index, bond]
 		BountyRejected(BountyIndex, Balance),
-		/// A bounty proposal is funded and became active. [index]
+		/// A bounty proposal is funded and became active. \[index\]
 		BountyBecameActive(BountyIndex),
 		/// A bounty is awarded to a beneficiary. [index, beneficiary]
 		BountyAwarded(BountyIndex, AccountId),
 		/// A bounty is claimed by beneficiary. [index, payout, beneficiary]
 		BountyClaimed(BountyIndex, Balance, AccountId),
-		/// A bounty is cancelled. [index]
+		/// A bounty is cancelled. \[index\]
 		BountyCanceled(BountyIndex),
-		/// A bounty expiry is extended. [index]
+		/// A bounty expiry is extended. \[index\]
 		BountyExtended(BountyIndex),
 	}
 );

substrate/primitives/npos-elections/compact/src/lib.rs

@@ -58,8 +58,8 @@ pub(crate) fn syn_err(message: &'static str) -> syn::Error {
 ///
 /// The given struct provides function to convert from/to Assignment:
 ///
-/// - [`from_assignment()`].
-/// - [`fn into_assignment()`].
+/// - `fn from_assignment<..>(..)`
+/// - `fn into_assignment<..>(..)`
 ///
 /// The generated struct is by default deriving both `Encode` and `Decode`. This is okay but could
 /// lead to many 0s in the solution. If prefixed with `#[compact]`, then a custom compact encoding

substrate/primitives/npos-elections/src/balancing.rs

@@ -36,7 +36,7 @@ use sp_std::prelude::*;
 /// change has been made (`difference = 0`).
 ///
 /// In almost all cases, a balanced solution will have a better score than an unbalanced solution,
-/// yet this is not 100% guaranteed because the first element of a [`ElectionScore`] does not
+/// yet this is not 100% guaranteed because the first element of a [`crate::ElectionScore`] does not
 /// directly related to balancing.
 ///
 /// Note that some reference implementation adopt an approach in which voters are balanced randomly

substrate/primitives/npos-elections/src/lib.rs

@@ -18,10 +18,10 @@
 //! - [`seq_phragmen`]: Implements the Phragmén Sequential Method. An un-ranked, relatively fast
 //!   election method that ensures PJR, but does not provide a constant factor approximation of the
 //!   maximin problem.
-//! - [`phragmms`]: Implements a hybrid approach inspired by Phragmén which is executed faster but
+//! - [`phragmms()`]: Implements a hybrid approach inspired by Phragmén which is executed faster but
 //!   it can achieve a constant factor approximation of the maximin problem, similar to that of the
 //!   MMS algorithm.
-//! - [`balance_solution`]: Implements the star balancing algorithm. This iterative process can push
+//! - [`balance`]: Implements the star balancing algorithm. This iterative process can push
 //!   a solution toward being more `balances`, which in turn can increase its score.
 //!
 //! ### Terminology
@@ -70,7 +70,7 @@
 //! `StakedAssignment`.
 //!
 //!
-//! More information can be found at: https://arxiv.org/abs/2004.12990
+//! More information can be found at: <https://arxiv.org/abs/2004.12990>
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -283,7 +283,7 @@ impl<AccountId: IdentifierT> Voter<AccountId> {
 		})
 	}
 
-	/// Same as [`try_normalize`] but the normalization is only limited between elected edges.
+	/// Same as [`Self::try_normalize`] but the normalization is only limited between elected edges.
 	pub fn try_normalize_elected(&mut self) -> Result<(), &'static str> {
 		let elected_edge_weights = self
 			.edges

substrate/primitives/npos-elections/src/phragmen.rs

@@ -108,9 +108,8 @@ pub fn seq_phragmen<AccountId: IdentifierT, P: PerThing>(
 /// `seq_phragmen` for more information. This function is left public in case a crate needs to use
 /// the implementation in a custom way.
 ///
-/// To create th inputs needed for this function, see [`crate::setup_inputs`].
-///
 /// This can only fail if the normalization fails.
+// To create the inputs needed for this function, see [`crate::setup_inputs`].
 pub fn seq_phragmen_core<AccountId: IdentifierT>(
 	rounds: usize,
 	candidates: Vec<CandidatePtr<AccountId>>,

substrate/primitives/npos-elections/src/reduce.rs

@@ -45,7 +45,7 @@
 //!
 //! ### Resources:
 //!
-//! 1. https://hackmd.io/JOn9x98iS0e0DPWQ87zGWg?view
+//! 1. <https://hackmd.io/JOn9x98iS0e0DPWQ87zGWg?view>
 
 use crate::node::{Node, NodeId, NodeRef, NodeRole};
 use crate::{ExtendedBalance, IdentifierT, StakedAssignment};

substrate/test-utils/runtime/src/lib.rs

@@ -15,7 +15,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! The Substrate runtime. This can be compiled with #[no_std], ready for Wasm.
+//! The Substrate runtime. This can be compiled with `#[no_std]`, ready for Wasm.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 

substrate/utils/prometheus/src/lib.rs

@@ -33,7 +33,7 @@ use std::net::SocketAddr;
 mod networking;
 mod sourced;
 
-pub use sourced::{SourcedCounter, SourcedGauge, MetricSource};
+pub use sourced::{SourcedCounter, SourcedGauge, MetricSource, SourcedMetric};
 
 #[cfg(target_os = "unknown")]
 pub use unknown_os::init_prometheus;