diff --git a/polkadot/core-primitives/src/lib.rs b/polkadot/core-primitives/src/lib.rs
index aa01cf8dfc..a74cdef3ad 100644
--- a/polkadot/core-primitives/src/lib.rs
+++ b/polkadot/core-primitives/src/lib.rs
@@ -60,7 +60,7 @@ pub type Hash = sp_core::H256;
 
 /// Unit type wrapper around [`type@Hash`] that represents a candidate hash.
 ///
-/// This type is produced by [`CandidateReceipt::hash`].
+/// This type is produced by `CandidateReceipt::hash`.
 ///
 /// This type makes it easy to enforce that a hash is a candidate hash on the type level.
 #[derive(Clone, Copy, Encode, Decode, Hash, Eq, PartialEq, Default, PartialOrd, Ord, TypeInfo)]
diff --git a/polkadot/node/core/parachains-inherent/src/lib.rs b/polkadot/node/core/parachains-inherent/src/lib.rs
index 3063147fb1..1de3cab32b 100644
--- a/polkadot/node/core/parachains-inherent/src/lib.rs
+++ b/polkadot/node/core/parachains-inherent/src/lib.rs
@@ -19,7 +19,7 @@
 //! Parachain backing and approval is an off-chain process, but the parachain needs to progress on
 //! chain as well. To make it progress on chain a block producer needs to forward information about
 //! the state of a parachain to the runtime. This information is forwarded through an inherent to
-//! the runtime. Here we provide the [`ParachainInherentDataProvider`] that requests the relevant
+//! the runtime. Here we provide the [`ParachainsInherentDataProvider`] that requests the relevant
 //! data from the provisioner subsystem and creates the the inherent data that the runtime will use
 //! to create an inherent.
 
diff --git a/polkadot/node/core/pvf/common/src/executor_intf.rs b/polkadot/node/core/pvf/common/src/executor_intf.rs
index 42ed4b79c7..79839149eb 100644
--- a/polkadot/node/core/pvf/common/src/executor_intf.rs
+++ b/polkadot/node/core/pvf/common/src/executor_intf.rs
@@ -141,7 +141,7 @@ impl Executor {
 	/// # Safety
 	///
 	/// The caller must ensure that the compiled artifact passed here was:
-	///   1) produced by [`prepare`],
+	///   1) produced by `prepare`,
 	///   2) was not modified,
 	///
 	/// Failure to adhere to these requirements might lead to crashes and arbitrary code execution.
@@ -171,7 +171,7 @@ impl Executor {
 	/// # Safety
 	///
 	/// The caller must ensure that the compiled artifact passed here was:
-	///   1) produced by [`prepare`],
+	///   1) produced by `prepare`,
 	///   2) was not modified,
 	///
 	/// Failure to adhere to these requirements might lead to crashes and arbitrary code execution.
diff --git a/polkadot/node/network/bridge/src/rx/mod.rs b/polkadot/node/network/bridge/src/rx/mod.rs
index 002919c5b0..51d248ca2d 100644
--- a/polkadot/node/network/bridge/src/rx/mod.rs
+++ b/polkadot/node/network/bridge/src/rx/mod.rs
@@ -92,7 +92,7 @@ impl<N, AD> NetworkBridgeRx<N, AD> {
 	/// discovery service.
 	///
 	/// This assumes that the network service has had the notifications protocol for the network
-	/// bridge already registered. See [`peers_sets_info`](peers_sets_info).
+	/// bridge already registered. See [`peer_sets_info`].
 	pub fn new(
 		network_service: N,
 		authority_discovery_service: AD,
diff --git a/polkadot/node/network/bridge/src/tx/mod.rs b/polkadot/node/network/bridge/src/tx/mod.rs
index e0ca633547..1b386ce123 100644
--- a/polkadot/node/network/bridge/src/tx/mod.rs
+++ b/polkadot/node/network/bridge/src/tx/mod.rs
@@ -65,7 +65,7 @@ impl<N, AD> NetworkBridgeTx<N, AD> {
 	/// discovery service.
 	///
 	/// This assumes that the network service has had the notifications protocol for the network
-	/// bridge already registered. See [`peers_sets_info`](peers_sets_info).
+	/// bridge already registered. See [`peer_sets_info`].
 	pub fn new(
 		network_service: N,
 		authority_discovery_service: AD,
diff --git a/polkadot/node/network/protocol/src/authority_discovery.rs b/polkadot/node/network/protocol/src/authority_discovery.rs
index 0cf11b93d1..beb5409d4a 100644
--- a/polkadot/node/network/protocol/src/authority_discovery.rs
+++ b/polkadot/node/network/protocol/src/authority_discovery.rs
@@ -30,12 +30,12 @@ use sc_network::{Multiaddr, PeerId};
 /// Needed for mocking in tests mostly.
 #[async_trait]
 pub trait AuthorityDiscovery: Send + Debug + 'static {
-	/// Get the addresses for the given [`AuthorityId`] from the local address cache.
+	/// Get the addresses for the given [`AuthorityDiscoveryId`] from the local address cache.
 	async fn get_addresses_by_authority_id(
 		&mut self,
 		authority: AuthorityDiscoveryId,
 	) -> Option<HashSet<Multiaddr>>;
-	/// Get the [`AuthorityId`] for the given [`PeerId`] from the local address cache.
+	/// Get the [`AuthorityDiscoveryId`] for the given [`PeerId`] from the local address cache.
 	async fn get_authority_ids_by_peer_id(
 		&mut self,
 		peer_id: PeerId,
diff --git a/polkadot/node/network/protocol/src/peer_set.rs b/polkadot/node/network/protocol/src/peer_set.rs
index b6f8c9dec2..c2163783c2 100644
--- a/polkadot/node/network/protocol/src/peer_set.rs
+++ b/polkadot/node/network/protocol/src/peer_set.rs
@@ -197,7 +197,7 @@ impl<T> IndexMut<PeerSet> for PerPeerSet<T> {
 
 /// Get `NonDefaultSetConfig`s for all available peer sets, at their default versions.
 ///
-/// Should be used during network configuration (added to [`NetworkConfiguration::extra_sets`])
+/// Should be used during network configuration (added to `NetworkConfiguration::extra_sets`)
 /// or shortly after startup to register the protocols with the network service.
 pub fn peer_sets_info(
 	is_authority: IsAuthority,
@@ -288,7 +288,7 @@ pub struct PeerSetProtocolNames {
 }
 
 impl PeerSetProtocolNames {
-	/// Construct [`PeerSetProtocols`] using `genesis_hash` and `fork_id`.
+	/// Construct [`PeerSetProtocolNames`] using `genesis_hash` and `fork_id`.
 	pub fn new(genesis_hash: Hash, fork_id: Option<&str>) -> Self {
 		let mut protocols = HashMap::new();
 		let mut names = HashMap::new();
diff --git a/polkadot/node/primitives/src/disputes/mod.rs b/polkadot/node/primitives/src/disputes/mod.rs
index ae8602dd5f..500b705be9 100644
--- a/polkadot/node/primitives/src/disputes/mod.rs
+++ b/polkadot/node/primitives/src/disputes/mod.rs
@@ -263,9 +263,9 @@ impl SignedDisputeStatement {
 		self.session_index
 	}
 
-	/// Convert a [`SignedFullStatement`] to a [`SignedDisputeStatement`]
+	/// Convert a unchecked backing statement to a [`SignedDisputeStatement`]
 	///
-	/// As [`SignedFullStatement`] contains only the validator index and
+	/// As the unchecked backing statement contains only the validator index and
 	/// not the validator public key, the public key must be passed as well,
 	/// along with the signing context.
 	///
diff --git a/polkadot/node/primitives/src/lib.rs b/polkadot/node/primitives/src/lib.rs
index 4cebc23ad3..baab07a9ba 100644
--- a/polkadot/node/primitives/src/lib.rs
+++ b/polkadot/node/primitives/src/lib.rs
@@ -463,8 +463,8 @@ impl CollationResult {
 /// Collation function.
 ///
 /// Will be called with the hash of the relay chain block the parachain block should be build on and
-/// the [`ValidationData`] that provides information about the state of the parachain on the relay
-/// chain.
+/// the [`PersistedValidationData`] that provides information about the state of the parachain on
+/// the relay chain.
 ///
 /// Returns an optional [`CollationResult`].
 #[cfg(not(target_os = "unknown"))]
@@ -498,7 +498,7 @@ impl std::fmt::Debug for CollationGenerationConfig {
 	}
 }
 
-/// Parameters for [`CollationGenerationMessage::SubmitCollation`].
+/// Parameters for `CollationGenerationMessage::SubmitCollation`.
 #[derive(Debug)]
 pub struct SubmitCollationParams {
 	/// The relay-parent the collation is built against.
@@ -634,7 +634,7 @@ pub struct ErasureChunk {
 }
 
 impl ErasureChunk {
-	/// Convert bounded Vec Proof to regular Vec<Vec<u8>>
+	/// Convert bounded Vec Proof to regular `Vec<Vec<u8>>`
 	pub fn proof(&self) -> &Proof {
 		&self.proof
 	}
diff --git a/polkadot/node/service/src/benchmarking.rs b/polkadot/node/service/src/benchmarking.rs
index 6955bc6d96..cfe1c873c0 100644
--- a/polkadot/node/service/src/benchmarking.rs
+++ b/polkadot/node/service/src/benchmarking.rs
@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Code related to benchmarking a [`crate::Client`].
+//! Code related to benchmarking a node.
 
 use polkadot_primitives::AccountId;
 use sc_client_api::UsageProvider;
diff --git a/polkadot/node/service/src/overseer.rs b/polkadot/node/service/src/overseer.rs
index 1c49577508..33127b638e 100644
--- a/polkadot/node/service/src/overseer.rs
+++ b/polkadot/node/service/src/overseer.rs
@@ -139,7 +139,7 @@ where
 	pub overseer_message_channel_capacity_override: Option<usize>,
 	/// Request-response protocol names source.
 	pub req_protocol_names: ReqProtocolNames,
-	/// [`PeerSet`] protocol names to protocols mapping.
+	/// `PeerSet` protocol names to protocols mapping.
 	pub peerset_protocol_names: PeerSetProtocolNames,
 	/// The offchain transaction pool factory.
 	pub offchain_transaction_pool_factory: OffchainTransactionPoolFactory<Block>,
diff --git a/polkadot/node/test/client/src/block_builder.rs b/polkadot/node/test/client/src/block_builder.rs
index 0987cef55c..b4ff050ff1 100644
--- a/polkadot/node/test/client/src/block_builder.rs
+++ b/polkadot/node/test/client/src/block_builder.rs
@@ -41,7 +41,7 @@ pub trait InitPolkadotBlockBuilder {
 	/// Init a Polkadot specific block builder at a specific block that works for the test runtime.
 	///
 	/// Same as [`InitPolkadotBlockBuilder::init_polkadot_block_builder`] besides that it takes a
-	/// [`BlockId`] to say which should be the parent block of the block that is being build.
+	/// `Hash` to say which should be the parent block of the block that is being build.
 	fn init_polkadot_block_builder_at(
 		&self,
 		hash: <Block as BlockT>::Hash,
diff --git a/polkadot/parachain/src/lib.rs b/polkadot/parachain/src/lib.rs
index 7bead23148..913d887e4a 100644
--- a/polkadot/parachain/src/lib.rs
+++ b/polkadot/parachain/src/lib.rs
@@ -27,10 +27,11 @@
 //! instance and exports a function `validate_block`.
 //!
 //! `validate` accepts as input two `i32` values, representing a pointer/length pair
-//! respectively, that encodes [`ValidationParams`].
+//! respectively, that encodes [`ValidationParams`](primitives::ValidationParams).
 //!
 //! `validate` returns an `u64` which is a pointer to an `u8` array and its length.
-//! The data in the array is expected to be a SCALE encoded [`ValidationResult`].
+//! The data in the array is expected to be a SCALE encoded
+//! [`ValidationResult`](primitives::ValidationResult).
 //!
 //! ASCII-diagram demonstrating the return data format:
 //!
diff --git a/polkadot/primitives/src/v5/mod.rs b/polkadot/primitives/src/v5/mod.rs
index 59fb6c927b..825d733c5f 100644
--- a/polkadot/primitives/src/v5/mod.rs
+++ b/polkadot/primitives/src/v5/mod.rs
@@ -1009,7 +1009,7 @@ impl<H, N> OccupiedCore<H, N> {
 pub struct ScheduledCore {
 	/// The ID of a para scheduled.
 	pub para_id: Id,
-	/// DEPRECATED: see: https://github.com/paritytech/polkadot/issues/7575
+	/// DEPRECATED: see: <https://github.com/paritytech/polkadot/issues/7575>
 	///
 	/// Will be removed in a future version.
 	pub collator: Option<CollatorId>,
@@ -1735,8 +1735,8 @@ pub struct SessionInfo {
 	///
 	/// Therefore:
 	/// ```ignore
-	/// 		assignment_keys.len() == validators.len() && validators.len() <= discovery_keys.len()
-	/// 	```
+	/// 	assignment_keys.len() == validators.len() && validators.len() <= discovery_keys.len()
+	/// ```
 	pub assignment_keys: Vec<AssignmentId>,
 	/// Validators in shuffled ordering - these are the validator groups as produced
 	/// by the `Scheduler` module for the session and are typically referred to by
diff --git a/polkadot/runtime/common/src/assigned_slots/migration.rs b/polkadot/runtime/common/src/assigned_slots/migration.rs
index 884d67222d..ea331fc212 100644
--- a/polkadot/runtime/common/src/assigned_slots/migration.rs
+++ b/polkadot/runtime/common/src/assigned_slots/migration.rs
@@ -63,9 +63,9 @@ pub mod v1 {
 		}
 	}
 
-	/// [`VersionUncheckedMigrateToV1`] wrapped in a
-	/// [`frame_support::migrations::VersionedRuntimeUpgrade`], ensuring the migration is only
-	/// performed when on-chain version is 0.
+	/// [`MigrateToV1`] wrapped in a
+	/// [`VersionedRuntimeUpgrade`](frame_support::migrations::VersionedRuntimeUpgrade), ensuring
+	/// the migration is only performed when on-chain version is 0.
 	#[cfg(feature = "experimental")]
 	pub type VersionCheckedMigrateToV1<T> = frame_support::migrations::VersionedRuntimeUpgrade<
 		0,
diff --git a/polkadot/runtime/common/src/elections.rs b/polkadot/runtime/common/src/elections.rs
index 5fd3971180..340e5c6e4a 100644
--- a/polkadot/runtime/common/src/elections.rs
+++ b/polkadot/runtime/common/src/elections.rs
@@ -18,7 +18,8 @@
 
 /// Implements the weight types for the elections module and a specific
 /// runtime.
-/// This macro should not be called directly; use [`impl_runtime_weights`] instead.
+/// This macro should not be called directly; use
+/// [`impl_runtime_weights`](crate::impl_runtime_weights!) instead.
 #[macro_export]
 macro_rules! impl_elections_weights {
 	($runtime:ident) => {
diff --git a/polkadot/runtime/common/src/lib.rs b/polkadot/runtime/common/src/lib.rs
index 61968e4883..46a9f7d12c 100644
--- a/polkadot/runtime/common/src/lib.rs
+++ b/polkadot/runtime/common/src/lib.rs
@@ -100,7 +100,7 @@ parameter_types! {
 }
 
 /// Parameterized slow adjusting fee updated based on
-/// https://research.web3.foundation/Polkadot/overview/token-economics#2-slow-adjusting-mechanism
+/// <https://research.web3.foundation/Polkadot/overview/token-economics#2-slow-adjusting-mechanism>
 pub type SlowAdjustingFeeUpdate<R> = TargetedFeeAdjustment<
 	R,
 	TargetBlockFullness,
diff --git a/polkadot/runtime/common/src/purchase.rs b/polkadot/runtime/common/src/purchase.rs
index 72795a733e..2520c45959 100644
--- a/polkadot/runtime/common/src/purchase.rs
+++ b/polkadot/runtime/common/src/purchase.rs
@@ -132,7 +132,7 @@ pub mod pallet {
 	#[pallet::event]
 	#[pallet::generate_deposit(pub(super) fn deposit_event)]
 	pub enum Event<T: Config> {
-		/// A [new] account was created.
+		/// A new account was created.
 		AccountCreated { who: T::AccountId },
 		/// Someone's account validity was updated.
 		ValidityUpdated { who: T::AccountId, validity: AccountValidity },
diff --git a/polkadot/runtime/parachains/src/assigner_on_demand/mod.rs b/polkadot/runtime/parachains/src/assigner_on_demand/mod.rs
index 5a60201e4f..0c9813d144 100644
--- a/polkadot/runtime/parachains/src/assigner_on_demand/mod.rs
+++ b/polkadot/runtime/parachains/src/assigner_on_demand/mod.rs
@@ -263,8 +263,8 @@ pub mod pallet {
 			Pallet::<T>::do_place_order(sender, max_amount, para_id, AllowDeath)
 		}
 
-		/// Same as the [`place_order_allow_death`] call , but with a check that placing the order
-		/// will not reap the account.
+		/// Same as the [`place_order_allow_death`](Self::place_order_allow_death) call , but with a
+		/// check that placing the order will not reap the account.
 		///
 		/// Parameters:
 		/// - `origin`: The sender of the call, funds will be withdrawn from this account.
diff --git a/polkadot/runtime/parachains/src/configuration.rs b/polkadot/runtime/parachains/src/configuration.rs
index accc01a2b1..fc24ac18ed 100644
--- a/polkadot/runtime/parachains/src/configuration.rs
+++ b/polkadot/runtime/parachains/src/configuration.rs
@@ -94,8 +94,8 @@ pub struct HostConfiguration<BlockNumber> {
 	///
 	/// If PVF pre-checking is enabled this should be greater than the maximum number of blocks
 	/// PVF pre-checking can take. Intuitively, this number should be greater than the duration
-	/// specified by [`pvf_voting_ttl`]. Unlike, [`pvf_voting_ttl`], this parameter uses blocks
-	/// as a unit.
+	/// specified by [`pvf_voting_ttl`](Self::pvf_voting_ttl). Unlike,
+	/// [`pvf_voting_ttl`](Self::pvf_voting_ttl), this parameter uses blocks as a unit.
 	#[cfg_attr(feature = "std", serde(alias = "validation_upgrade_frequency"))]
 	pub validation_upgrade_cooldown: BlockNumber,
 	/// The delay, in blocks, after which an upgrade of the validation code is applied.
@@ -113,14 +113,15 @@ pub struct HostConfiguration<BlockNumber> {
 	/// been completed.
 	///
 	/// Note, there are situations in which `expected_at` in the past. For example, if
-	/// [`paras_availability_period`] is less than the delay set by
-	/// this field or if PVF pre-check took more time than the delay. In such cases, the upgrade is
-	/// further at the earliest possible time determined by [`minimum_validation_upgrade_delay`].
+	/// [`paras_availability_period`](Self::paras_availability_period) is less than the delay set
+	/// by this field or if PVF pre-check took more time than the delay. In such cases, the upgrade
+	/// is further at the earliest possible time determined by
+	/// [`minimum_validation_upgrade_delay`](Self::minimum_validation_upgrade_delay).
 	///
 	/// The rationale for this delay has to do with relay-chain reversions. In case there is an
 	/// invalid candidate produced with the new version of the code, then the relay-chain can
-	/// revert [`validation_upgrade_delay`] many blocks back and still find the new code in the
-	/// storage by hash.
+	/// revert [`validation_upgrade_delay`](Self::validation_upgrade_delay) many blocks back and
+	/// still find the new code in the storage by hash.
 	///
 	/// [#4601]: https://github.com/paritytech/polkadot/issues/4601
 	pub validation_upgrade_delay: BlockNumber,
@@ -229,7 +230,8 @@ pub struct HostConfiguration<BlockNumber> {
 	pub pvf_voting_ttl: SessionIndex,
 	/// The lower bound number of blocks an upgrade can be scheduled.
 	///
-	/// Typically, upgrade gets scheduled [`validation_upgrade_delay`] relay-chain blocks after
+	/// Typically, upgrade gets scheduled
+	/// [`validation_upgrade_delay`](Self::validation_upgrade_delay) relay-chain blocks after
 	/// the relay-parent of the parablock that signalled the validation code upgrade. However,
 	/// in the case a pre-checking voting was concluded in a longer duration the upgrade will be
 	/// scheduled to the next block.
@@ -240,7 +242,8 @@ pub struct HostConfiguration<BlockNumber> {
 	/// To prevent that, we introduce the minimum number of blocks after which the upgrade can be
 	/// scheduled. This number is controlled by this field.
 	///
-	/// This value should be greater than [`paras_availability_period`].
+	/// This value should be greater than
+	/// [`paras_availability_period`](Self::paras_availability_period).
 	pub minimum_validation_upgrade_delay: BlockNumber,
 }
 
diff --git a/polkadot/runtime/parachains/src/dmp.rs b/polkadot/runtime/parachains/src/dmp.rs
index 490c2fa1cd..bc7491a2c6 100644
--- a/polkadot/runtime/parachains/src/dmp.rs
+++ b/polkadot/runtime/parachains/src/dmp.rs
@@ -81,9 +81,9 @@ impl From<QueueDownwardMessageError> for SendError {
 	}
 }
 
-/// An error returned by [`check_processed_downward_messages`] that indicates an acceptance check
-/// didn't pass.
-pub enum ProcessedDownwardMessagesAcceptanceErr {
+/// An error returned by [`Pallet::check_processed_downward_messages`] that indicates an acceptance
+/// check didn't pass.
+pub(crate) enum ProcessedDownwardMessagesAcceptanceErr {
 	/// If there are pending messages then `processed_downward_messages` should be at least 1,
 	AdvancementRule,
 	/// `processed_downward_messages` should not be greater than the number of pending messages.
diff --git a/polkadot/runtime/parachains/src/hrmp.rs b/polkadot/runtime/parachains/src/hrmp.rs
index a3ce6e2d8a..3a4d2df4b6 100644
--- a/polkadot/runtime/parachains/src/hrmp.rs
+++ b/polkadot/runtime/parachains/src/hrmp.rs
@@ -149,17 +149,17 @@ pub struct HrmpChannel {
 	pub recipient_deposit: Balance,
 }
 
-/// An error returned by [`check_hrmp_watermark`] that indicates an acceptance criteria check
-/// didn't pass.
-pub enum HrmpWatermarkAcceptanceErr<BlockNumber> {
+/// An error returned by [`Pallet::check_hrmp_watermark`] that indicates an acceptance criteria
+/// check didn't pass.
+pub(crate) enum HrmpWatermarkAcceptanceErr<BlockNumber> {
 	AdvancementRule { new_watermark: BlockNumber, last_watermark: BlockNumber },
 	AheadRelayParent { new_watermark: BlockNumber, relay_chain_parent_number: BlockNumber },
 	LandsOnBlockWithNoMessages { new_watermark: BlockNumber },
 }
 
-/// An error returned by [`check_outbound_hrmp`] that indicates an acceptance criteria check
+/// An error returned by [`Pallet::check_outbound_hrmp`] that indicates an acceptance criteria check
 /// didn't pass.
-pub enum OutboundHrmpAcceptanceErr {
+pub(crate) enum OutboundHrmpAcceptanceErr {
 	MoreMessagesThanPermitted { sent: u32, permitted: u32 },
 	NotSorted { idx: u32 },
 	NoSuchChannel { idx: u32, channel_id: HrmpChannelId },
diff --git a/polkadot/runtime/parachains/src/inclusion/mod.rs b/polkadot/runtime/parachains/src/inclusion/mod.rs
index e60aac0080..ceec7d718e 100644
--- a/polkadot/runtime/parachains/src/inclusion/mod.rs
+++ b/polkadot/runtime/parachains/src/inclusion/mod.rs
@@ -416,10 +416,10 @@ enum AcceptanceCheckErr<BlockNumber> {
 	OutboundHrmp(hrmp::OutboundHrmpAcceptanceErr),
 }
 
-/// An error returned by [`check_upward_messages`] that indicates a violation of one of acceptance
-/// criteria rules.
+/// An error returned by [`Pallet::check_upward_messages`] that indicates a violation of one of
+/// acceptance criteria rules.
 #[cfg_attr(test, derive(PartialEq))]
-pub enum UmpAcceptanceCheckErr {
+pub(crate) enum UmpAcceptanceCheckErr {
 	/// The maximal number of messages that can be submitted in one batch was exceeded.
 	MoreMessagesThanPermitted { sent: u32, permitted: u32 },
 	/// The maximal size of a single message was exceeded.
diff --git a/polkadot/runtime/parachains/src/lib.rs b/polkadot/runtime/parachains/src/lib.rs
index 056eef3542..64365f17b7 100644
--- a/polkadot/runtime/parachains/src/lib.rs
+++ b/polkadot/runtime/parachains/src/lib.rs
@@ -63,8 +63,6 @@ pub trait FeeTracker {
 }
 
 /// Schedule a para to be initialized at the start of the next session with the given genesis data.
-///
-/// See [`paras::Pallet::schedule_para_initialize`] for more details.
 pub fn schedule_para_initialize<T: paras::Config>(
 	id: ParaId,
 	genesis: paras::ParaGenesisArgs,
@@ -73,8 +71,6 @@ pub fn schedule_para_initialize<T: paras::Config>(
 }
 
 /// Schedule a para to be cleaned up at the start of the next session.
-///
-/// See [`paras::Pallet::schedule_para_cleanup`] for more details.
 pub fn schedule_para_cleanup<T: paras::Config>(id: primitives::Id) -> Result<(), ()> {
 	<paras::Pallet<T>>::schedule_para_cleanup(id).map_err(|_| ())
 }
@@ -90,8 +86,6 @@ pub fn schedule_parachain_downgrade<T: paras::Config>(id: ParaId) -> Result<(),
 }
 
 /// Schedules a validation code upgrade to a parachain with the given id.
-///
-/// This simply calls [`crate::paras::Pallet::schedule_code_upgrade_external`].
 pub fn schedule_code_upgrade<T: paras::Config>(
 	id: ParaId,
 	new_code: ValidationCode,
@@ -100,8 +94,6 @@ pub fn schedule_code_upgrade<T: paras::Config>(
 }
 
 /// Sets the current parachain head with the given id.
-///
-/// This simply calls [`crate::paras::Pallet::set_current_head`].
 pub fn set_current_head<T: paras::Config>(id: ParaId, new_head: HeadData) {
 	paras::Pallet::<T>::set_current_head(id, new_head)
 }
diff --git a/polkadot/runtime/parachains/src/paras_inherent/misc.rs b/polkadot/runtime/parachains/src/paras_inherent/misc.rs
index e77b26b9e1..dac9e6e256 100644
--- a/polkadot/runtime/parachains/src/paras_inherent/misc.rs
+++ b/polkadot/runtime/parachains/src/paras_inherent/misc.rs
@@ -40,7 +40,7 @@ impl<T> IndexedRetain<T> for Vec<T> {
 }
 
 /// Helper trait until `is_sorted_by` is stabilized.
-/// TODO: https://github.com/rust-lang/rust/issues/53485
+/// TODO: <https://github.com/rust-lang/rust/issues/53485>
 pub trait IsSortedBy<T> {
 	fn is_sorted_by<F>(self, cmp: F) -> bool
 	where
diff --git a/polkadot/runtime/parachains/src/runtime_api_impl/v5.rs b/polkadot/runtime/parachains/src/runtime_api_impl/v5.rs
index cd15796897..bac1268f53 100644
--- a/polkadot/runtime/parachains/src/runtime_api_impl/v5.rs
+++ b/polkadot/runtime/parachains/src/runtime_api_impl/v5.rs
@@ -345,7 +345,7 @@ pub fn on_chain_votes<T: paras_inherent::Config>() -> Option<ScrapedOnChainVotes
 	<paras_inherent::Pallet<T>>::on_chain_votes()
 }
 
-/// Submits an PVF pre-checking vote. See [`paras::Pallet::submit_pvf_check_statement`].
+/// Submits an PVF pre-checking vote.
 pub fn submit_pvf_check_statement<T: paras::Config>(
 	stmt: PvfCheckStatement,
 	signature: ValidatorSignature,
@@ -353,8 +353,7 @@ pub fn submit_pvf_check_statement<T: paras::Config>(
 	<paras::Pallet<T>>::submit_pvf_check_statement(stmt, signature)
 }
 
-/// Returns the list of all PVF code hashes that require pre-checking. See
-/// [`paras::Pallet::pvfs_require_precheck`].
+/// Returns the list of all PVF code hashes that require pre-checking.
 pub fn pvfs_require_precheck<T: paras::Config>() -> Vec<ValidationCodeHash> {
 	<paras::Pallet<T>>::pvfs_require_precheck()
 }
diff --git a/polkadot/utils/staking-miner/src/opts.rs b/polkadot/utils/staking-miner/src/opts.rs
index ecffe45310..4cf4d0a765 100644
--- a/polkadot/utils/staking-miner/src/opts.rs
+++ b/polkadot/utils/staking-miner/src/opts.rs
@@ -88,10 +88,10 @@ pub(crate) struct MonitorConfig {
 	///
 	/// `--submission-strategy always`: always submit.
 	///
-	/// `--submission-strategy "percent-better <percent>"`: submit if the submission is `n` percent
+	/// `--submission-strategy "percent-better percent"`: submit if the submission is `n` percent
 	/// better.
 	///
-	/// `--submission-strategy "no-worse-than  <percent>"`: submit if submission is no more than
+	/// `--submission-strategy "no-worse-than percent"`: submit if submission is no more than
 	/// `n` percent worse.
 	#[clap(long, default_value = "if-leading")]
 	pub submission_strategy: SubmissionStrategy,
@@ -190,8 +190,8 @@ pub(crate) enum Solver {
 /// Possible options:
 /// * --submission-strategy if-leading: only submit if leading
 /// * --submission-strategy always: always submit
-/// * --submission-strategy "percent-better <percent>": submit if submission is `n` percent better.
-/// * --submission-strategy "no-worse-than<percent>": submit if submission is no more than `n`
+/// * --submission-strategy "percent-better percent": submit if submission is `n` percent better.
+/// * --submission-strategy "no-worse-than percent": submit if submission is no more than `n`
 ///   percent worse.
 impl FromStr for SubmissionStrategy {
 	type Err = String;
diff --git a/polkadot/xcm/xcm-builder/src/pay.rs b/polkadot/xcm/xcm-builder/src/pay.rs
index e36d26e425..ae0f9ee340 100644
--- a/polkadot/xcm/xcm-builder/src/pay.rs
+++ b/polkadot/xcm/xcm-builder/src/pay.rs
@@ -193,7 +193,7 @@ pub struct LocatableAssetId {
 	pub location: MultiLocation,
 }
 
-/// Adapter `struct` which implements a conversion from any `AssetKind` into a [`LocatableAsset`]
+/// Adapter `struct` which implements a conversion from any `AssetKind` into a [`LocatableAssetId`]
 /// value using a fixed `Location` for the `location` field.
 pub struct FixedLocation<Location>(sp_std::marker::PhantomData<Location>);
 impl<Location: Get<MultiLocation>, AssetKind: Into<AssetId>> Convert<AssetKind, LocatableAssetId>
diff --git a/polkadot/xcm/xcm-builder/src/process_xcm_message.rs b/polkadot/xcm/xcm-builder/src/process_xcm_message.rs
index 8130d17329..808cf5521d 100644
--- a/polkadot/xcm/xcm-builder/src/process_xcm_message.rs
+++ b/polkadot/xcm/xcm-builder/src/process_xcm_message.rs
@@ -26,7 +26,7 @@ use sp_std::{fmt::Debug, marker::PhantomData};
 use sp_weights::{Weight, WeightMeter};
 use xcm::prelude::*;
 
-/// A message processor that delegates execution to an [`XcmExecutor`].
+/// A message processor that delegates execution to an `XcmExecutor`.
 pub struct ProcessXcmMessage<MessageOrigin, XcmExecutor, Call>(
 	PhantomData<(MessageOrigin, XcmExecutor, Call)>,
 );
diff --git a/substrate/frame/support/procedural/src/pallet/expand/storage.rs b/substrate/frame/support/procedural/src/pallet/expand/storage.rs
index 1a941f6cb3..c01f0f3926 100644
--- a/substrate/frame/support/procedural/src/pallet/expand/storage.rs
+++ b/substrate/frame/support/procedural/src/pallet/expand/storage.rs
@@ -22,7 +22,6 @@ use crate::{
 		Def,
 	},
 };
-use itertools::Itertools;
 use quote::ToTokens;
 use std::{collections::HashMap, ops::IndexMut};
 use syn::spanned::Spanned;
@@ -443,11 +442,14 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream {
 
 			let cfg_attrs = &storage.cfg_attrs;
 
-			// If the storage item is public, just link to it rather than copy-pasting the docs.
+			// If the storage item is public, link it and otherwise just mention it.
+			//
+			// We can not just copy the docs from a non-public type as it may links to internal
+			// types which makes the compiler very unhappy :(
 			let getter_doc_line = if matches!(storage.vis, syn::Visibility::Public(_)) {
 				format!("An auto-generated getter for [`{}`].", storage.ident)
 			} else {
-				storage.docs.iter().map(|d| d.into_token_stream().to_string()).join("\n")
+				format!("An auto-generated getter for `{}`.", storage.ident)
 			};
 
 			match &storage.metadata {