Fail docs on warnings (#5923)

* change (ci): docs job optimized; runs every commit; fails on warnings

* change (ci): rename jobs; temporary allow failing

* change (ci): better warnings filtering

* fix (ci): hotfix Docker release

* test (ci): run docs job with flags

* test (ci): pwd fails

* change (ci): pass just //doc dir as an artifact; debug

* change (ci): return to the previous structure; undebug

* change (ci): typo

* rebase on upstream 2

* fix the jobname

* Fix some warnings (#7079)

* Partial fix for transaction priority (#7034)

* Partial fix for priority stuff.

* Small fix

* Fix tests.

* Update frame/transaction-payment/src/lib.rs

Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>

* Better doc

Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>

* What happens if we remove wat? (#7056)

* What happens if we remove wat?

* Update Cargo.lock

* Make SlashingSpans Public (#6961)

* Make SlashingSpans Public

Offchain Applications will often need to inspect this type because it is directly used in staking election, thus worthy of being `pub`. Rest of the slashing api can remain private, only this and the `fn last_non_zero_slash()` of `SlashingSpans` are of interest.

* Update frame/staking/src/lib.rs

* client/authority-discovery/src/service: Improve docs (#7059)

* Decrease poll interval (#7063)

* Remove unused code (#7027)

Signed-off-by: Jimmy Chu <jimmychu0807@gmail.com>

* Disambiguate `BlockNumber` type in `decl_module` (#7061)

* Disambiguate `BlockNumber` type in `decl_module`

* fix `frame-support-tests`

* fix ui tests

* fix trait order

* Implement `FromStr` for `Ss58AddressFormat` (#7068)

* Implement `FromStr` for `Ss58AddressFormat`

* Update primitives/core/src/crypto.rs

Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com>

Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com>

* Set reserved nodes with offchain worker. (#6996)

* add offchain worker api to set reserved nodes.

* new offchain api to get node public key.

* node public key from converter

* refactor set reserved nodes ocw api.

* new ndoe authorization pallet

* remove unnecessary clone and more.

* more

* tests for node authorization pallet

* remove dependency

* fix build

* more tests.

* refactor

* Update primitives/core/src/offchain/testing.rs

Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>

* Update frame/node-authorization/src/lib.rs

Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>

* Update frame/node-authorization/src/lib.rs

Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>

* Update frame/node-authorization/src/lib.rs

Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>

* format code

* expose NetworkService

* remove NetworkStateInfo in offchain

* replace NodePublicKey with PeerId.

* set max length of peer id.

* clear more

* use BTreeSet for set of peers.

* decode opaque peer id.

* extract NetworkProvider for client offchain.

* use OpaquePeerId in node authorization pallet.

* fix test

* better documentation

* fix test

* doc

* more fix

* Update primitives/core/src/offchain/mod.rs

Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>

* Update client/offchain/src/api.rs

Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>

* derive serialize and deserialize

Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>
Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>

* Fix some warnings

Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>
Co-authored-by: Sergei Shulepov <sergei@parity.io>
Co-authored-by: Max Inden <mail@max-inden.de>
Co-authored-by: s3krit <pugh@s3kr.it>
Co-authored-by: Jimmy Chu <jimmy@parity.io>
Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com>
Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>
Co-authored-by: kaichao <kaichaosuna@gmail.com>
Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>

* Fix more doc errors

* More doc fixes

* Remove subdb to make `rustdoc` happy

* Make the line length check happy

* Fix compilation error

* Another try

* Allow unused

Co-authored-by: Dan Forbes <dan@danforbes.dev>
Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>
Co-authored-by: Sergei Shulepov <sergei@parity.io>
Co-authored-by: Max Inden <mail@max-inden.de>
Co-authored-by: s3krit <pugh@s3kr.it>
Co-authored-by: Jimmy Chu <jimmy@parity.io>
Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com>
Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>
Co-authored-by: kaichao <kaichaosuna@gmail.com>
Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>
Co-authored-by: Bastian Köcher <git@kchr.de>

substrate/.gitlab-ci.yml

@@ -13,7 +13,7 @@
 #   image:                           paritytech/tools:latest # Any docker image (required)
 #   allow_failure:                   true # Allow the pipeline to continue if this job fails (default: false)
 #   dependencies:
-#     - build-rust-doc-release # Any jobs that are required to run before this job (optional)
+#     - build-rust-doc # Any jobs that are required to run before this job (optional)
 #   variables:
 #     MY_ENVIRONMENT_VARIABLE:       "some useful value" # Environment variables passed to the job (optional)
 #   script:
@@ -476,23 +476,25 @@ build-macos-subkey:
   tags:
     - osx
 
-build-rust-doc-release:
+build-rust-doc:
   stage:                           build
   <<:                              *docker-env
   <<:                              *docker-env-only
   allow_failure:                   true
+  variables:
+    <<:                            *default-vars
+    RUSTFLAGS:                     -Dwarnings
   artifacts:
     name:                          "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}-doc"
     when:                          on_success
     expire_in:                     7 days
     paths:
-    - ./crate-docs
-  <<:                              *build-only
+    - ./crate-docs/
   script:
     - rm -f ./crate-docs/index.html # use it as an indicator if the job succeeds
-    - BUILD_DUMMY_WASM_BINARY=1 RUSTDOCFLAGS="--html-in-header $(pwd)/.maintain/rustdoc-header.html"
-        time cargo +nightly doc --release --all --verbose
-    - cp -R ./target/doc ./crate-docs
+    - BUILD_DUMMY_WASM_BINARY=1 RUSTDOCFLAGS="--html-in-header $(pwd)/.maintain/rustdoc-header.html"  
+        time cargo +nightly doc --no-deps --workspace --all-features --verbose
+    - mv ./target/doc ./crate-docs
     - echo "<meta http-equiv=refresh content=0;url=sc_service/index.html>" > ./crate-docs/index.html
     - sccache -s
 
@@ -670,7 +672,7 @@ publish-s3-doc:
   image:                           paritytech/awscli:latest
   allow_failure:                   true
   needs:
-    - job:                         build-rust-doc-release
+    - job:                         build-rust-doc
       artifacts:                   true
   <<:                              *build-only
   <<:                              *kubernetes-build

substrate/client/cli/src/arg_enums.rs

@@ -172,8 +172,6 @@ arg_enum! {
 	pub enum Database {
 		// Facebooks RocksDB
 		RocksDb,
-		// Subdb. https://github.com/paritytech/subdb/
-		SubDb,
 		// ParityDb. https://github.com/paritytech/parity-db/
 		ParityDb,
 	}

substrate/client/cli/src/config.rs

@@ -222,9 +222,6 @@ pub trait CliConfiguration<DCV: DefaultConfigurationValues = ()>: Sized {
 				path: base_path.join("db"),
 				cache_size,
 			},
-			Database::SubDb => DatabaseConfig::SubDb {
-				path: base_path.join("subdb"),
-			},
 			Database::ParityDb => DatabaseConfig::ParityDb {
 				path: base_path.join("paritydb"),
 			},

substrate/client/db/Cargo.toml

@@ -50,4 +50,3 @@ default = []
 test-helpers = []
 with-kvdb-rocksdb = ["kvdb-rocksdb"]
 with-parity-db = ["parity-db"]
-with-subdb = []

substrate/client/db/src/lib.rs

@@ -44,8 +44,6 @@ mod utils;
 mod stats;
 #[cfg(feature = "with-parity-db")]
 mod parity_db;
-#[cfg(feature = "with-subdb")]
-mod subdb;
 
 use std::sync::Arc;
 use std::path::{Path, PathBuf};
@@ -287,12 +285,6 @@ pub enum DatabaseSettingsSrc {
 		path: PathBuf,
 	},
 
-	/// Load a Subdb database from a given path.
-	SubDb {
-		/// Path to the database.
-		path: PathBuf,
-	},
-
 	/// Use a custom already-open database.
 	Custom(Arc<dyn Database<DbHash>>),
 }
@@ -303,7 +295,6 @@ impl DatabaseSettingsSrc {
 		match self {
 			DatabaseSettingsSrc::RocksDb { path, .. } => Some(path.as_path()),
 			DatabaseSettingsSrc::ParityDb { path, .. } => Some(path.as_path()),
-			DatabaseSettingsSrc::SubDb { path, .. } => Some(path.as_path()),
 			DatabaseSettingsSrc::Custom(_) => None,
 		}
 	}
@@ -321,7 +312,6 @@ impl std::fmt::Display for DatabaseSettingsSrc {
 		let name = match self {
 			DatabaseSettingsSrc::RocksDb { .. } => "RocksDb",
 			DatabaseSettingsSrc::ParityDb { .. } => "ParityDb",
-			DatabaseSettingsSrc::SubDb { .. } => "SubDb",
 			DatabaseSettingsSrc::Custom(_) => "Custom",
 		};
 		write!(f, "{}", name)

substrate/client/db/src/subdb.rs

@@ -1,88 +0,0 @@
-// This file is part of Substrate.
-
-// Copyright (C) 2017-2020 Parity Technologies (UK) Ltd.
-// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
-
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-// GNU General Public License for more details.
-
-// You should have received a copy of the GNU General Public License
-// along with this program. If not, see <https://www.gnu.org/licenses/>.
-/// A `Database` adapter for subdb.
-
-use sp_database::{self, ColumnId};
-use parking_lot::RwLock;
-use blake2_rfc::blake2b::blake2b;
-use codec::Encode;
-use subdb::{Database, KeyType};
-
-/// A database hidden behind an RwLock, so that it implements Send + Sync.
-///
-/// Construct by creating a `Database` and then using `.into()`.
-pub struct DbAdapter<H: KeyType>(RwLock<Database<H>>);
-
-/// Wrap RocksDb database into a trait object that implements `sp_database::Database`
-pub fn open<H: KeyType + 'static>(
-	path: &std::path::Path,
-	_num_columns: u32,
-) -> Result<std::sync::Arc<dyn sp_database::Database<H>>, subdb::Error> {
-	let db = subdb::Options::from_path(path.into()).open()?;
-	Ok(std::sync::Arc::new(DbAdapter(RwLock::new(db))))
-}
-
-impl<H: KeyType> sp_database::Database<H> for DbAdapter<H> {
-	fn get(&self, col: ColumnId, key: &[u8]) -> Option<Vec<u8>> {
-		let mut hash = H::default();
-		(col, key).using_encoded(|d|
-			hash.as_mut().copy_from_slice(blake2b(32, &[], d).as_bytes())
-		);
-		self.0.read().get(&hash)
-	}
-
-	fn with_get(&self, col: ColumnId, key: &[u8], f: &mut dyn FnMut(&[u8])) {
-		let mut hash = H::default();
-		(col, key).using_encoded(|d|
-			hash.as_mut().copy_from_slice(blake2b(32, &[], d).as_bytes())
-		);
-		let _ = self.0.read().get_ref(&hash).map(|d| f(d.as_ref()));
-	}
-
-	fn set(&self, col: ColumnId, key: &[u8], value: &[u8]) {
-		let mut hash = H::default();
-		(col, key).using_encoded(|d|
-			hash.as_mut().copy_from_slice(blake2b(32, &[], d).as_bytes())
-		);
-		self.0.write().insert(&value, &hash);
-	}
-
-	fn remove(&self, col: ColumnId, key: &[u8]) {
-		let mut hash = H::default();
-		(col, key).using_encoded(|d|
-			hash.as_mut().copy_from_slice(blake2b(32, &[], d).as_bytes())
-		);
-		let _ = self.0.write().remove(&hash);
-	}
-
-	fn lookup(&self, hash: &H) -> Option<Vec<u8>> {
-		self.0.read().get(hash)
-	}
-
-	fn with_lookup(&self, hash: &H, f: &mut dyn FnMut(&[u8])) {
-		let _ = self.0.read().get_ref(hash).map(|d| f(d.as_ref()));
-	}
-
-	fn store(&self, hash: &H, preimage: &[u8]) {
-		self.0.write().insert(preimage, hash);
-	}
-
-	fn release(&self, hash: &H) {
-		let _ = self.0.write().remove(hash);
-	}
-}

substrate/client/db/src/utils.rs

@@ -212,11 +212,12 @@ pub fn open_database<Block: BlockT>(
 	config: &DatabaseSettings,
 	db_type: DatabaseType,
 ) -> sp_blockchain::Result<Arc<dyn Database<DbHash>>> {
-	let db_open_error = |feat| Err(
+	#[allow(unused)]
+	fn db_open_error(feat: &'static str) -> sp_blockchain::Error {
 		sp_blockchain::Error::Backend(
 			format!("`{}` feature not enabled, database can not be opened", feat),
-		),
-	);
+		)
+	}
 
 	let db: Arc<dyn Database<DbHash>> = match &config.source {
 		#[cfg(any(feature = "with-kvdb-rocksdb", test))]
@@ -257,16 +258,7 @@ pub fn open_database<Block: BlockT>(
 		},
 		#[cfg(not(any(feature = "with-kvdb-rocksdb", test)))]
 		DatabaseSettingsSrc::RocksDb { .. } => {
-			return db_open_error("with-kvdb-rocksdb");
-		},
-		#[cfg(feature = "with-subdb")]
-		DatabaseSettingsSrc::SubDb { path } => {
-			crate::subdb::open(&path, NUM_COLUMNS)
-				.map_err(|e| sp_blockchain::Error::Backend(format!("{:?}", e)))?
-		},
-		#[cfg(not(feature = "with-subdb"))]
-		DatabaseSettingsSrc::SubDb { .. } => {
-			return db_open_error("with-subdb");
+			return Err(db_open_error("with-kvdb-rocksdb"));
 		},
 		#[cfg(feature = "with-parity-db")]
 		DatabaseSettingsSrc::ParityDb { path } => {
@@ -275,7 +267,7 @@ pub fn open_database<Block: BlockT>(
 		},
 		#[cfg(not(feature = "with-parity-db"))]
 		DatabaseSettingsSrc::ParityDb { .. } => {
-			return db_open_error("with-parity-db");
+			return Err(db_open_error("with-parity-db"))
 		},
 		DatabaseSettingsSrc::Custom(db) => db.clone(),
 	};

substrate/client/network/src/lib.rs

@@ -267,7 +267,10 @@ pub mod network_state;
 #[doc(inline)]
 pub use libp2p::{multiaddr, Multiaddr, PeerId};
 pub use protocol::{event::{DhtEvent, Event, ObservedRole}, sync::SyncState, PeerInfo};
-pub use service::{NetworkService, NetworkWorker, RequestFailure, OutboundFailure};
+pub use service::{
+	NetworkService, NetworkWorker, RequestFailure, OutboundFailure, NotificationSender,
+	NotificationSenderReady,
+};
 
 pub use sc_peerset::ReputationChange;
 use sp_runtime::traits::{Block as BlockT, NumberFor};

substrate/client/network/src/request_responses.rs

@@ -16,7 +16,7 @@
 
 //! Collection of request-response protocols.
 //!
-//! The [`RequestResponses`] struct defined in this module provides support for zero or more
+//! The [`RequestResponse`] struct defined in this module provides support for zero or more
 //! so-called "request-response" protocols.
 //!
 //! A request-response protocol works in the following way:
@@ -29,7 +29,7 @@
 //! - Requests have a certain time limit before they time out. This time includes the time it
 //! takes to send/receive the request and response.
 //!
-//! - If provided, a ["requests processing"](RequestResponseConfig::inbound_queue) channel
+//! - If provided, a ["requests processing"](ProtocolConfig::inbound_queue) channel
 //! is used to handle incoming requests.
 //!
 
@@ -108,7 +108,7 @@ pub struct IncomingRequest {
 	pub peer: PeerId,
 
 	/// Request sent by the remote. Will always be smaller than
-	/// [`RequestResponseConfig::max_request_size`].
+	/// [`ProtocolConfig::max_request_size`].
 	pub payload: Vec<u8>,
 
 	/// Channel to send back the response to.

substrate/client/network/src/service.rs

@@ -639,7 +639,7 @@ impl<B: BlockT + 'static, H: ExHashT> NetworkService<B, H> {
 	/// >			preventing the message from being delivered.
 	///
 	/// The protocol must have been registered with `register_notifications_protocol` or
-	/// `NetworkConfiguration::notifications_protocols`.
+	/// [`NetworkConfiguration::notifications_protocols`](crate::config::NetworkConfiguration::notifications_protocols).
 	///
 	pub fn write_notification(&self, target: PeerId, engine_id: ConsensusEngineId, message: Vec<u8>) {
 		// We clone the `NotificationsSink` in order to be able to unlock the network-wide
@@ -682,10 +682,9 @@ impl<B: BlockT + 'static, H: ExHashT> NetworkService<B, H> {
 	/// 2.  [`NotificationSenderReady::send`] enqueues the notification for sending. This operation
 	/// can only fail if the underlying notification substream or connection has suddenly closed.
 	///
-	/// An error is returned either by `notification_sender`, by [`NotificationSender::wait`],
-	/// or by [`NotificationSenderReady::send`] if there exists no open notifications substream
-	/// with that combination of peer and protocol, or if the remote has asked to close the
-	/// notifications substream. If that happens, it is guaranteed that an
+	/// An error is returned by [`NotificationSenderReady::send`] if there exists no open
+	/// notifications substream with that combination of peer and protocol, or if the remote
+	/// has asked to close the notifications substream. If that happens, it is guaranteed that an
 	/// [`Event::NotificationStreamClosed`] has been generated on the stream returned by
 	/// [`NetworkService::event_stream`].
 	///
@@ -696,7 +695,7 @@ impl<B: BlockT + 'static, H: ExHashT> NetworkService<B, H> {
 	/// in which case enqueued notifications will be lost.
 	///
 	/// The protocol must have been registered with `register_notifications_protocol` or
-	/// `NetworkConfiguration::notifications_protocols`.
+	/// [`NetworkConfiguration::notifications_protocols`](crate::config::NetworkConfiguration::notifications_protocols).
 	///
 	/// # Usage
 	///
@@ -801,7 +800,8 @@ impl<B: BlockT + 'static, H: ExHashT> NetworkService<B, H> {
 	/// Such restrictions, if desired, need to be enforced at the call site(s).
 	///
 	/// The protocol must have been registered through
-	/// [`NetworkConfiguration::request_response_protocols`].
+	/// [`NetworkConfiguration::request_response_protocols`](
+	/// crate::config::NetworkConfiguration::request_response_protocols).
 	pub async fn request(
 		&self,
 		target: PeerId,

substrate/frame/assets/src/lib.rs

@@ -230,11 +230,11 @@ decl_event! {
 		<T as Trait>::Balance,
 		<T as Trait>::AssetId,
 	{
-		/// Some assets were issued. [asset_id, owner, total_supply]
+		/// Some assets were issued. \[asset_id, owner, total_supply\]
 		Issued(AssetId, AccountId, Balance),
-		/// Some assets were transferred. [asset_id, from, to, amount]
+		/// Some assets were transferred. \[asset_id, from, to, amount\]
 		Transferred(AssetId, AccountId, AccountId, Balance),
-		/// Some assets were destroyed. [asset_id, owner, balance]
+		/// Some assets were destroyed. \[asset_id, owner, balance\]
 		Destroyed(AssetId, AccountId, Balance),
 	}
 }

substrate/frame/atomic-swap/src/lib.rs

@@ -189,12 +189,12 @@ decl_event!(
 		AccountId = <T as system::Trait>::AccountId,
 		PendingSwap = PendingSwap<T>,
 	{
-		/// Swap created. [account, proof, swap]
+		/// Swap created. \[account, proof, swap\]
 		NewSwap(AccountId, HashedProof, PendingSwap),
 		/// Swap claimed. The last parameter indicates whether the execution succeeds. 
-		/// [account, proof, success]
+		/// \[account, proof, success\]
 		SwapClaimed(AccountId, HashedProof, bool),
-		/// Swap cancelled. [account, proof]
+		/// Swap cancelled. \[account, proof\]
 		SwapCancelled(AccountId, HashedProof),
 	}
 );

substrate/frame/balances/src/lib.rs

@@ -235,24 +235,24 @@ decl_event!(
 		<T as frame_system::Trait>::AccountId,
 		<T as Trait<I>>::Balance
 	{
-		/// An account was created with some free balance. [account, free_balance]
+		/// An account was created with some free balance. \[account, free_balance\]
 		Endowed(AccountId, Balance),
 		/// An account was removed whose balance was non-zero but below ExistentialDeposit,
-		/// resulting in an outright loss. [account, balance]
+		/// resulting in an outright loss. \[account, balance\]
 		DustLost(AccountId, Balance),
-		/// Transfer succeeded. [from, to, value]
+		/// Transfer succeeded. \[from, to, value\]
 		Transfer(AccountId, AccountId, Balance),
-		/// A balance was set by root. [who, free, reserved]
+		/// A balance was set by root. \[who, free, reserved\]
 		BalanceSet(AccountId, Balance, Balance),
-		/// Some amount was deposited (e.g. for transaction fees). [who, deposit]
+		/// Some amount was deposited (e.g. for transaction fees). \[who, deposit\]
 		Deposit(AccountId, Balance),
-		/// Some balance was reserved (moved from free to reserved). [who, value]
+		/// Some balance was reserved (moved from free to reserved). \[who, value\]
 		Reserved(AccountId, Balance),
-		/// Some balance was unreserved (moved from reserved to free). [who, value]
+		/// Some balance was unreserved (moved from reserved to free). \[who, value\]
 		Unreserved(AccountId, Balance),
 		/// Some balance was moved from the reserve of the first account to the second account.
 		/// Final argument indicates the destination balance type.
-		/// [from, to, balance, destination_status]
+		/// \[from, to, balance, destination_status\]
 		ReserveRepatriated(AccountId, AccountId, Balance, Status),
 	}
 );

substrate/frame/collective/src/lib.rs

@@ -175,26 +175,26 @@ decl_event! {
 	{
 		/// A motion (given hash) has been proposed (by given account) with a threshold (given
 		/// `MemberCount`).
-		/// [account, proposal_index, proposal_hash, threshold]
+		/// \[account, proposal_index, proposal_hash, threshold\]
 		Proposed(AccountId, ProposalIndex, Hash, MemberCount),
 		/// A motion (given hash) has been voted on by given account, leaving
 		/// a tally (yes votes and no votes given respectively as `MemberCount`).
-		/// [account, proposal_hash, voted, yes, no]
+		/// \[account, proposal_hash, voted, yes, no\]
 		Voted(AccountId, Hash, bool, MemberCount, MemberCount),
 		/// A motion was approved by the required threshold.
-		/// [proposal_hash]
+		/// \[proposal_hash\]
 		Approved(Hash),
 		/// A motion was not approved by the required threshold.
-		/// [proposal_hash]
+		/// \[proposal_hash\]
 		Disapproved(Hash),
 		/// A motion was executed; result will be `Ok` if it returned without error.
-		/// [proposal_hash, result]
+		/// \[proposal_hash, result\]
 		Executed(Hash, DispatchResult),
 		/// A single member did some action; result will be `Ok` if it returned without error.
-		/// [proposal_hash, result]
+		/// \[proposal_hash, result\]
 		MemberExecuted(Hash, DispatchResult),
 		/// A proposal was closed because its threshold was reached or after its duration was up.
-		/// [proposal_hash, yes, no]
+		/// \[proposal_hash, yes, no\]
 		Closed(Hash, MemberCount, MemberCount),
 	}
 }

substrate/frame/contracts/src/lib.rs

@@ -686,11 +686,11 @@ decl_event! {
 		<T as frame_system::Trait>::AccountId,
 		<T as frame_system::Trait>::Hash
 	{
-		/// Contract deployed by address at the specified address. [owner, contract]
+		/// Contract deployed by address at the specified address. \[owner, contract\]
 		Instantiated(AccountId, AccountId),
 
 		/// Contract has been evicted and is now in tombstone state.
-		/// [contract, tombstone]
+		/// \[contract, tombstone\]
 		/// 
 		/// # Params
 		///
@@ -699,7 +699,7 @@ decl_event! {
 		Evicted(AccountId, bool),
 
 		/// Restoration for a contract has been successful.
-		/// [donor, dest, code_hash, rent_allowance]
+		/// \[donor, dest, code_hash, rent_allowance\]
 		/// 
 		/// # Params
 		///
@@ -710,14 +710,14 @@ decl_event! {
 		Restored(AccountId, AccountId, Hash, Balance),
 
 		/// Code with the specified hash has been stored.
-		/// [code_hash]
+		/// \[code_hash\]
 		CodeStored(Hash),
 
-		/// Triggered when the current [schedule] is updated.
+		/// Triggered when the current \[schedule\] is updated.
 		ScheduleUpdated(u32),
 
 		/// An event deposited upon execution of a contract from the account.
-		/// [account, data]
+		/// \[account, data\]
 		ContractExecution(AccountId, Vec<u8>),
 	}
 }

substrate/frame/democracy/src/lib.rs

@@ -434,41 +434,43 @@ decl_event! {
 		<T as frame_system::Trait>::Hash,
 		<T as frame_system::Trait>::BlockNumber,
 	{
-		/// A motion has been proposed by a public account. [proposal_index, deposit]
+		/// A motion has been proposed by a public account. \[proposal_index, deposit\]
 		Proposed(PropIndex, Balance),
-		/// A public proposal has been tabled for referendum vote. [proposal_index, deposit, depositors]
+		/// A public proposal has been tabled for referendum vote. \[proposal_index, deposit, depositors\]
 		Tabled(PropIndex, Balance, Vec<AccountId>),
 		/// An external proposal has been tabled.
 		ExternalTabled,
-		/// A referendum has begun. [ref_index, threshold]
+		/// A referendum has begun. \[ref_index, threshold\]
 		Started(ReferendumIndex, VoteThreshold),
-		/// A proposal has been approved by referendum. [ref_index]
+		/// A proposal has been approved by referendum. \[ref_index\]
 		Passed(ReferendumIndex),
-		/// A proposal has been rejected by referendum. [ref_index]
+		/// A proposal has been rejected by referendum. \[ref_index\]
 		NotPassed(ReferendumIndex),
-		/// A referendum has been cancelled. [ref_index]
+		/// A referendum has been cancelled. \[ref_index\]
 		Cancelled(ReferendumIndex),
-		/// A proposal has been enacted. [ref_index, is_ok]
+		/// A proposal has been enacted. \[ref_index, is_ok\]
 		Executed(ReferendumIndex, bool),
-		/// An account has delegated their vote to another account. [who, target]
+		/// An account has delegated their vote to another account. \[who, target\]
 		Delegated(AccountId, AccountId),
-		/// An [account] has cancelled a previous delegation operation.
+		/// An \[account\] has cancelled a previous delegation operation.
 		Undelegated(AccountId),
-		/// An external proposal has been vetoed. [who, proposal_hash, until]
+		/// An external proposal has been vetoed. \[who, proposal_hash, until\]
 		Vetoed(AccountId, Hash, BlockNumber),
-		/// A proposal's preimage was noted, and the deposit taken. [proposal_hash, who, deposit]
+		/// A proposal's preimage was noted, and the deposit taken. \[proposal_hash, who, deposit\]
 		PreimageNoted(Hash, AccountId, Balance),
 		/// A proposal preimage was removed and used (the deposit was returned).
-		/// [proposal_hash, provider, deposit]
+		/// \[proposal_hash, provider, deposit\]
 		PreimageUsed(Hash, AccountId, Balance),
-		/// A proposal could not be executed because its preimage was invalid. [proposal_hash, ref_index]
+		/// A proposal could not be executed because its preimage was invalid.
+		/// \[proposal_hash, ref_index\]
 		PreimageInvalid(Hash, ReferendumIndex),
-		/// A proposal could not be executed because its preimage was missing. [proposal_hash, ref_index]
+		/// A proposal could not be executed because its preimage was missing.
+		/// \[proposal_hash, ref_index\]
 		PreimageMissing(Hash, ReferendumIndex),
 		/// A registered preimage was removed and the deposit collected by the reaper.
-		/// [proposal_hash, provider, deposit, reaper]
+		/// \[proposal_hash, provider, deposit, reaper\]
 		PreimageReaped(Hash, AccountId, Balance, AccountId),
-		/// An [account] has been unlocked successfully.
+		/// An \[account\] has been unlocked successfully.
 		Unlocked(AccountId),
 	}
 }

substrate/frame/elections-phragmen/src/lib.rs

@@ -709,21 +709,21 @@ decl_event!(
 		Balance = BalanceOf<T>,
 		<T as frame_system::Trait>::AccountId,
 	{
-		/// A new term with [new_members]. This indicates that enough candidates existed to run the
+		/// A new term with \[new_members\]. This indicates that enough candidates existed to run the
 		/// election, not that enough have has been elected. The inner value must be examined for
-		/// this purpose. A `NewTerm([])` indicates that some candidates got their bond slashed and
+		/// this purpose. A `NewTerm(\[\])` indicates that some candidates got their bond slashed and
 		/// none were elected, whilst `EmptyTerm` means that no candidates existed to begin with.
 		NewTerm(Vec<(AccountId, Balance)>),
 		/// No (or not enough) candidates existed for this round. This is different from
-		/// `NewTerm([])`. See the description of `NewTerm`.
+		/// `NewTerm(\[\])`. See the description of `NewTerm`.
 		EmptyTerm,
-		/// A [member] has been removed. This should always be followed by either `NewTerm` ot
+		/// A \[member\] has been removed. This should always be followed by either `NewTerm` ot
 		/// `EmptyTerm`.
 		MemberKicked(AccountId),
-		/// A [member] has renounced their candidacy.
+		/// A \[member\] has renounced their candidacy.
 		MemberRenounced(AccountId),
 		/// A voter was reported with the the report being successful or not.
-		/// [voter, reporter, success]
+		/// \[voter, reporter, success\]
 		VoterReported(AccountId, AccountId, bool),
 	}
 );

substrate/frame/elections/src/lib.rs

@@ -700,14 +700,14 @@ decl_module! {
 
 decl_event!(
 	pub enum Event<T> where <T as frame_system::Trait>::AccountId {
-		/// Reaped [voter, reaper].
+		/// Reaped \[voter, reaper\].
 		VoterReaped(AccountId, AccountId),
-		/// Slashed [reaper].
+		/// Slashed \[reaper\].
 		BadReaperSlashed(AccountId),
-		/// A tally (for approval votes of [seats]) has started.
+		/// A tally (for approval votes of \[seats\]) has started.
 		TallyStarted(u32),
 		/// A tally (for approval votes of seat(s)) has ended (with one or more new members). 
-		/// [incoming, outgoing]
+		/// \[incoming, outgoing\]
 		TallyFinalized(Vec<AccountId>, Vec<AccountId>),
 	}
 );

substrate/frame/evm/src/lib.rs

@@ -261,17 +261,17 @@ decl_event! {
 	{
 		/// Ethereum events from contracts.
 		Log(Log),
-		/// A contract has been created at given [address].
+		/// A contract has been created at given \[address\].
 		Created(H160),
-		/// A [contract] was attempted to be created, but the execution failed.
+		/// A \[contract\] was attempted to be created, but the execution failed.
 		CreatedFailed(H160),
-		/// A [contract] has been executed successfully with states applied.
+		/// A \[contract\] has been executed successfully with states applied.
 		Executed(H160),
-		/// A [contract] has been executed with errors. States are reverted with only gas fees applied.
+		/// A \[contract\] has been executed with errors. States are reverted with only gas fees applied.
 		ExecutedFailed(H160),
-		/// A deposit has been made at a given address. [sender, address, value]
+		/// A deposit has been made at a given address. \[sender, address, value\]
 		BalanceDeposit(AccountId, H160, U256),
-		/// A withdrawal has been made from a given address. [sender, address, value]
+		/// A withdrawal has been made from a given address. \[sender, address, value\]
 		BalanceWithdraw(AccountId, H160, U256),
 	}
 }

substrate/frame/example-offchain-worker/src/lib.rs

@@ -166,7 +166,7 @@ decl_event!(
 	/// Events generated by the module.
 	pub enum Event<T> where AccountId = <T as frame_system::Trait>::AccountId {
 		/// Event generated when new price is accepted to contribute to the average.
-		/// [price, who]
+		/// \[price, who\]
 		NewPrice(u32, AccountId),
 	}
 );

substrate/frame/generic-asset/src/lib.rs

@@ -493,15 +493,15 @@ decl_event!(
 		<T as Trait>::AssetId,
 		AssetOptions = AssetOptions<<T as Trait>::Balance, <T as frame_system::Trait>::AccountId>
 	{
-		/// Asset created. [asset_id, creator, asset_options]
+		/// Asset created. \[asset_id, creator, asset_options\]
 		Created(AssetId, AccountId, AssetOptions),
-		/// Asset transfer succeeded. [asset_id, from, to, amount]
+		/// Asset transfer succeeded. \[asset_id, from, to, amount\]
 		Transferred(AssetId, AccountId, AccountId, Balance),
-		/// Asset permission updated. [asset_id, new_permissions]
+		/// Asset permission updated. \[asset_id, new_permissions\]
 		PermissionUpdated(AssetId, PermissionLatest<AccountId>),
-		/// New asset minted. [asset_id, account, amount]
+		/// New asset minted. \[asset_id, account, amount\]
 		Minted(AssetId, AccountId, Balance),
-		/// Asset burned. [asset_id, account, amount]
+		/// Asset burned. \[asset_id, account, amount\]
 		Burned(AssetId, AccountId, Balance),
 	}
 );

substrate/frame/grandpa/src/lib.rs

@@ -170,7 +170,7 @@ pub enum StoredState<N> {
 
 decl_event! {
 	pub enum Event {
-		/// New authority set has been applied. [authority_set]
+		/// New authority set has been applied. \[authority_set\]
 		NewAuthorities(AuthorityList),
 		/// Current authority set has been paused.
 		Paused,

substrate/frame/identity/src/lib.rs

@@ -462,27 +462,27 @@ decl_storage! {
 
 decl_event!(
 	pub enum Event<T> where AccountId = <T as frame_system::Trait>::AccountId, Balance = BalanceOf<T> {
-		/// A name was set or reset (which will remove all judgements). [who]
+		/// A name was set or reset (which will remove all judgements). \[who\]
 		IdentitySet(AccountId),
-		/// A name was cleared, and the given balance returned. [who, deposit]
+		/// A name was cleared, and the given balance returned. \[who, deposit\]
 		IdentityCleared(AccountId, Balance),
-		/// A name was removed and the given balance slashed. [who, deposit]
+		/// A name was removed and the given balance slashed. \[who, deposit\]
 		IdentityKilled(AccountId, Balance),
-		/// A judgement was asked from a registrar. [who, registrar_index]
+		/// A judgement was asked from a registrar. \[who, registrar_index\]
 		JudgementRequested(AccountId, RegistrarIndex),
-		/// A judgement request was retracted. [who, registrar_index]
+		/// A judgement request was retracted. \[who, registrar_index\]
 		JudgementUnrequested(AccountId, RegistrarIndex),
-		/// A judgement was given by a registrar. [target, registrar_index]
+		/// A judgement was given by a registrar. \[target, registrar_index\]
 		JudgementGiven(AccountId, RegistrarIndex),
-		/// A registrar was added. [registrar_index]
+		/// A registrar was added. \[registrar_index\]
 		RegistrarAdded(RegistrarIndex),
-		/// A sub-identity was added to an identity and the deposit paid. [sub, main, deposit]
+		/// A sub-identity was added to an identity and the deposit paid. \[sub, main, deposit\]
 		SubIdentityAdded(AccountId, AccountId, Balance),
 		/// A sub-identity was removed from an identity and the deposit freed.
-		/// [sub, main, deposit]
+		/// \[sub, main, deposit\]
 		SubIdentityRemoved(AccountId, AccountId, Balance),
 		/// A sub-identity was cleared, and the given deposit repatriated from the
-		/// main identity account to the sub-identity account. [sub, main, deposit]
+		/// main identity account to the sub-identity account. \[sub, main, deposit\]
 		SubIdentityRevoked(AccountId, AccountId, Balance),
 	}
 );

substrate/frame/im-online/src/lib.rs

@@ -276,11 +276,11 @@ decl_event!(
 		<T as Trait>::AuthorityId,
 		IdentificationTuple = IdentificationTuple<T>,
 	{
-		/// A new heartbeat was received from `AuthorityId` [authority_id]
+		/// A new heartbeat was received from `AuthorityId` \[authority_id\]
 		HeartbeatReceived(AuthorityId),
 		/// At the end of the session, no offence was committed.
 		AllGood,
-		/// At the end of the session, at least one validator was found to be [offline].
+		/// At the end of the session, at least one validator was found to be \[offline\].
 		SomeOffline(Vec<IdentificationTuple>),
 	}
 );

substrate/frame/indices/src/lib.rs

@@ -95,11 +95,11 @@ decl_event!(
 		<T as frame_system::Trait>::AccountId,
 		<T as Trait>::AccountIndex
 	{
-		/// A account index was assigned. [who, index]
+		/// A account index was assigned. \[who, index\]
 		IndexAssigned(AccountId, AccountIndex),
-		/// A account index has been freed up (unassigned). [index]
+		/// A account index has been freed up (unassigned). \[index\]
 		IndexFreed(AccountIndex),
-		/// A account index has been frozen to its current account ID. [who, index]
+		/// A account index has been frozen to its current account ID. \[who, index\]
 		IndexFrozen(AccountIndex, AccountId),
 	}
 );

substrate/frame/multisig/src/lib.rs

@@ -197,13 +197,14 @@ decl_event! {
 		BlockNumber = <T as system::Trait>::BlockNumber,
 		CallHash = [u8; 32]
 	{
-		/// A new multisig operation has begun. [approving, multisig, call_hash]
+		/// A new multisig operation has begun. \[approving, multisig, call_hash\]
 		NewMultisig(AccountId, AccountId, CallHash),
-		/// A multisig operation has been approved by someone. [approving, timepoint, multisig, call_hash]
+		/// A multisig operation has been approved by someone.
+		/// \[approving, timepoint, multisig, call_hash\]
 		MultisigApproval(AccountId, Timepoint<BlockNumber>, AccountId, CallHash),
-		/// A multisig operation has been executed. [approving, timepoint, multisig, call_hash]
+		/// A multisig operation has been executed. \[approving, timepoint, multisig, call_hash\]
 		MultisigExecuted(AccountId, Timepoint<BlockNumber>, AccountId, CallHash, DispatchResult),
-		/// A multisig operation has been cancelled. [cancelling, timepoint, multisig, call_hash]
+		/// A multisig operation has been cancelled. \[cancelling, timepoint, multisig, call_hash\]
 		MultisigCancelled(AccountId, Timepoint<BlockNumber>, AccountId, CallHash),
 	}
 }

substrate/frame/nicks/src/lib.rs

@@ -86,15 +86,15 @@ decl_storage! {
 
 decl_event!(
 	pub enum Event<T> where AccountId = <T as frame_system::Trait>::AccountId, Balance = BalanceOf<T> {
-		/// A name was set. [who]
+		/// A name was set. \[who\]
 		NameSet(AccountId),
-		/// A name was forcibly set. [target]
+		/// A name was forcibly set. \[target\]
 		NameForced(AccountId),
-		/// A name was changed. [who]
+		/// A name was changed. \[who\]
 		NameChanged(AccountId),
-		/// A name was cleared, and the given balance returned. [who, deposit]
+		/// A name was cleared, and the given balance returned. \[who, deposit\]
 		NameCleared(AccountId, Balance),
-		/// A name was removed and the given balance slashed. [target, deposit]
+		/// A name was removed and the given balance slashed. \[target, deposit\]
 		NameKilled(AccountId, Balance),
 	}
 );

substrate/frame/offences/src/lib.rs

@@ -112,7 +112,7 @@ decl_event!(
 		/// There is an offence reported of the given `kind` happened at the `session_index` and
 		/// (kind-specific) time slot. This event is not deposited for duplicate slashes. last
 		/// element indicates of the offence was applied (true) or queued (false) 
-		/// [kind, timeslot, applied].
+		/// \[kind, timeslot, applied\].
 		Offence(Kind, OpaqueTimeSlot, bool),
 	}
 );

substrate/frame/proxy/src/lib.rs

@@ -191,12 +191,12 @@ decl_event! {
 		ProxyType = <T as Trait>::ProxyType,
 		Hash = CallHashOf<T>,
 	{
-		/// A proxy was executed correctly, with the given [result].
+		/// A proxy was executed correctly, with the given \[result\].
 		ProxyExecuted(DispatchResult),
 		/// Anonymous account has been created by new proxy with given
-		/// disambiguation index and proxy type. [anonymous, who, proxy_type, disambiguation_index]
+		/// disambiguation index and proxy type. \[anonymous, who, proxy_type, disambiguation_index\]
 		AnonymousCreated(AccountId, AccountId, ProxyType, u16),
-		/// An announcement was placed to make a call in the future. [real, proxy, call_hash]
+		/// An announcement was placed to make a call in the future. \[real, proxy, call_hash\]
 		Announced(AccountId, AccountId, Hash),
 	}
 }

substrate/frame/recovery/src/lib.rs

@@ -264,21 +264,21 @@ decl_event! {
 	pub enum Event<T> where
 		AccountId = <T as system::Trait>::AccountId,
 	{
-		/// A recovery process has been set up for an [account].
+		/// A recovery process has been set up for an \[account\].
 		RecoveryCreated(AccountId),
 		/// A recovery process has been initiated for lost account by rescuer account.
-		/// [lost, rescuer]
+		/// \[lost, rescuer\]
 		RecoveryInitiated(AccountId, AccountId),
 		/// A recovery process for lost account by rescuer account has been vouched for by sender.
-		/// [lost, rescuer, sender]
+		/// \[lost, rescuer, sender\]
 		RecoveryVouched(AccountId, AccountId, AccountId),
 		/// A recovery process for lost account by rescuer account has been closed.
-		/// [lost, rescuer]
+		/// \[lost, rescuer\]
 		RecoveryClosed(AccountId, AccountId),
 		/// Lost account has been successfully recovered by rescuer account.
-		/// [lost, rescuer]
+		/// \[lost, rescuer\]
 		AccountRecovered(AccountId, AccountId),
-		/// A recovery process has been removed for an [account].
+		/// A recovery process has been removed for an \[account\].
 		RecoveryRemoved(AccountId),
 	}
 }

substrate/frame/scheduler/src/lib.rs

@@ -177,11 +177,11 @@ decl_storage! {
 
 decl_event!(
 	pub enum Event<T> where <T as system::Trait>::BlockNumber {
-		/// Scheduled some task. [when, index]
+		/// Scheduled some task. \[when, index\]
 		Scheduled(BlockNumber, u32),
-		/// Canceled some task. [when, index]
+		/// Canceled some task. \[when, index\]
 		Canceled(BlockNumber, u32),
-		/// Dispatched some task. [task, id, result]
+		/// Dispatched some task. \[task, id, result\]
 		Dispatched(TaskAddress<BlockNumber>, Option<Vec<u8>>, DispatchResult),
 	}
 );

substrate/frame/session/src/lib.rs

@@ -484,7 +484,7 @@ decl_storage! {
 
 decl_event!(
 	pub enum Event {
-		/// New session has happened. Note that the argument is the [session_index], not the block
+		/// New session has happened. Note that the argument is the \[session_index\], not the block
 		/// number as the type might suggest.
 		NewSession(SessionIndex),
 	}

substrate/frame/society/src/lib.rs

@@ -1111,40 +1111,40 @@ decl_event! {
 		AccountId = <T as system::Trait>::AccountId,
 		Balance = BalanceOf<T, I>
 	{
-		/// The society is founded by the given identity. [founder]
+		/// The society is founded by the given identity. \[founder\]
 		Founded(AccountId),
 		/// A membership bid just happened. The given account is the candidate's ID and their offer
-		/// is the second. [candidate_id, offer]
+		/// is the second. \[candidate_id, offer\]
 		Bid(AccountId, Balance),
 		/// A membership bid just happened by vouching. The given account is the candidate's ID and
-		/// their offer is the second. The vouching party is the third. [candidate_id, offer, vouching]
+		/// their offer is the second. The vouching party is the third. \[candidate_id, offer, vouching\]
 		Vouch(AccountId, Balance, AccountId),
-		/// A [candidate] was dropped (due to an excess of bids in the system).
+		/// A \[candidate\] was dropped (due to an excess of bids in the system).
 		AutoUnbid(AccountId),
-		/// A [candidate] was dropped (by their request).
+		/// A \[candidate\] was dropped (by their request).
 		Unbid(AccountId),
-		/// A [candidate] was dropped (by request of who vouched for them).
+		/// A \[candidate\] was dropped (by request of who vouched for them).
 		Unvouch(AccountId),
 		/// A group of candidates have been inducted. The batch's primary is the first value, the
-		/// batch in full is the second. [primary, candidates]
+		/// batch in full is the second. \[primary, candidates\]
 		Inducted(AccountId, Vec<AccountId>),
-		/// A suspended member has been judged. [who, judged]
+		/// A suspended member has been judged. \[who, judged\]
 		SuspendedMemberJudgement(AccountId, bool),
-		/// A [candidate] has been suspended
+		/// A \[candidate\] has been suspended
 		CandidateSuspended(AccountId),
-		/// A [member] has been suspended
+		/// A \[member\] has been suspended
 		MemberSuspended(AccountId),
-		/// A [member] has been challenged
+		/// A \[member\] has been challenged
 		Challenged(AccountId),
-		/// A vote has been placed [candidate, voter, vote]
+		/// A vote has been placed \[candidate, voter, vote\]
 		Vote(AccountId, AccountId, bool),
-		/// A vote has been placed for a defending member [voter, vote]
+		/// A vote has been placed for a defending member \[voter, vote\]
 		DefenderVote(AccountId, bool),
-		/// A new [max] member count has been set
+		/// A new \[max\] member count has been set
 		NewMaxMembers(u32),
-		/// Society is unfounded. [founder]
+		/// Society is unfounded. \[founder\]
 		Unfounded(AccountId),
-		/// Some funds were deposited into the society account. [value]
+		/// Some funds were deposited into the society account. \[value\]
 		Deposit(Balance),
 	}
 }

substrate/frame/staking/src/lib.rs

@@ -1241,29 +1241,29 @@ decl_event!(
 	pub enum Event<T> where Balance = BalanceOf<T>, <T as frame_system::Trait>::AccountId {
 		/// The era payout has been set; the first balance is the validator-payout; the second is
 		/// the remainder from the maximum amount of reward.
-		/// [era_index, validator_payout, remainder]
+		/// \[era_index, validator_payout, remainder\]
 		EraPayout(EraIndex, Balance, Balance),
-		/// The staker has been rewarded by this amount. [stash, amount]
+		/// The staker has been rewarded by this amount. \[stash, amount\]
 		Reward(AccountId, Balance),
 		/// One validator (and its nominators) has been slashed by the given amount.
-		/// [validator, amount]
+		/// \[validator, amount\]
 		Slash(AccountId, Balance),
 		/// An old slashing report from a prior era was discarded because it could
-		/// not be processed. [session_index]
+		/// not be processed. \[session_index\]
 		OldSlashingReportDiscarded(SessionIndex),
-		/// A new set of stakers was elected with the given [compute].
+		/// A new set of stakers was elected with the given \[compute\].
 		StakingElection(ElectionCompute),
-		/// A new solution for the upcoming election has been stored. [compute]
+		/// A new solution for the upcoming election has been stored. \[compute\]
 		SolutionStored(ElectionCompute),
-		/// An account has bonded this amount. [stash, amount]
+		/// An account has bonded this amount. \[stash, amount\]
 		///
 		/// NOTE: This event is only emitted when funds are bonded via a dispatchable. Notably,
 		/// it will not be emitted for staking rewards when they are added to stake.
 		Bonded(AccountId, Balance),
-		/// An account has unbonded this amount. [stash, amount]
+		/// An account has unbonded this amount. \[stash, amount\]
 		Unbonded(AccountId, Balance),
 		/// An account has called `withdraw_unbonded` and removed unbonding chunks worth `Balance`
-		/// from the unlocking queue. [stash, amount]
+		/// from the unlocking queue. \[stash, amount\]
 		Withdrawn(AccountId, Balance),
 	}
 );

substrate/frame/sudo/src/lib.rs

@@ -225,11 +225,11 @@ decl_module! {
 
 decl_event!(
 	pub enum Event<T> where AccountId = <T as frame_system::Trait>::AccountId {
-		/// A sudo just took place. [result]
+		/// A sudo just took place. \[result\]
 		Sudid(DispatchResult),
-		/// The [sudoer] just switched identity; the old key is supplied.
+		/// The \[sudoer\] just switched identity; the old key is supplied.
 		KeyChanged(AccountId),
-		/// A sudo just took place. [result]
+		/// A sudo just took place. \[result\]
 		SudoAsDone(bool),
 	}
 );

substrate/frame/support/src/dispatch.rs

@@ -106,7 +106,7 @@ impl<T> Parameter for T where T: Codec + EncodeLike + Clone + Eq + fmt::Debug {}
 /// ### Shorthand Example
 ///
 /// The macro automatically expands a shorthand function declaration to return the
-/// [`DispatchResult`](dispatch::DispatchResult) type. These functions are the same:
+/// [`DispatchResult`] type. These functions are the same:
 ///
 /// ```
 /// # #[macro_use]

substrate/frame/system/src/lib.rs

@@ -483,15 +483,15 @@ decl_storage! {
 decl_event!(
 	/// Event for the System module.
 	pub enum Event<T> where AccountId = <T as Trait>::AccountId {
-		/// An extrinsic completed successfully. [info]
+		/// An extrinsic completed successfully. \[info\]
 		ExtrinsicSuccess(DispatchInfo),
-		/// An extrinsic failed. [error, info]
+		/// An extrinsic failed. \[error, info\]
 		ExtrinsicFailed(DispatchError, DispatchInfo),
 		/// `:code` was updated.
 		CodeUpdated,
-		/// A new [account] was created.
+		/// A new \[account\] was created.
 		NewAccount(AccountId),
-		/// An [account] was reaped.
+		/// An \[account\] was reaped.
 		KilledAccount(AccountId),
 	}
 );

substrate/frame/treasury/src/lib.rs

@@ -277,27 +277,28 @@ decl_event!(
 		<T as frame_system::Trait>::AccountId,
 		<T as frame_system::Trait>::Hash,
 	{
-		/// New proposal. [proposal_index]
+		/// New proposal. \[proposal_index\]
 		Proposed(ProposalIndex),
-		/// We have ended a spend period and will now allocate funds. [budget_remaining]
+		/// We have ended a spend period and will now allocate funds. \[budget_remaining\]
 		Spending(Balance),
-		/// Some funds have been allocated. [proposal_index, award, beneficiary]
+		/// Some funds have been allocated. \[proposal_index, award, beneficiary\]
 		Awarded(ProposalIndex, Balance, AccountId),
-		/// A proposal was rejected; funds were slashed. [proposal_index, slashed]
+		/// A proposal was rejected; funds were slashed. \[proposal_index, slashed\]
 		Rejected(ProposalIndex, Balance),
-		/// Some of our funds have been burnt. [burn]
+		/// Some of our funds have been burnt. \[burn\]
 		Burnt(Balance),
-		/// Spending has finished; this is the amount that rolls over until next spend. [budget_remaining]
+		/// Spending has finished; this is the amount that rolls over until next spend.
+		/// \[budget_remaining\]
 		Rollover(Balance),
-		/// Some funds have been deposited. [deposit]
+		/// Some funds have been deposited. \[deposit\]
 		Deposit(Balance),
-		/// A new tip suggestion has been opened. [tip_hash]
+		/// A new tip suggestion has been opened. \[tip_hash\]
 		NewTip(Hash),
-		/// A tip suggestion has reached threshold and is closing. [tip_hash]
+		/// A tip suggestion has reached threshold and is closing. \[tip_hash\]
 		TipClosing(Hash),
-		/// A tip suggestion has been closed. [tip_hash, who, payout]
+		/// A tip suggestion has been closed. \[tip_hash, who, payout\]
 		TipClosed(Hash, AccountId, Balance),
-		/// A tip suggestion has been retracted. [tip_hash]
+		/// A tip suggestion has been retracted. \[tip_hash\]
 		TipRetracted(Hash),
 	}
 );

substrate/frame/utility/src/lib.rs

@@ -98,7 +98,7 @@ decl_event! {
 	/// Events type.
 	pub enum Event {
 		/// Batch of dispatches did not complete fully. Index of first failing dispatch given, as
-		/// well as the error. [index, error]
+		/// well as the error. \[index, error\]
 		BatchInterrupted(u32, DispatchError),
 		/// Batch of dispatches completed fully with no error.
 		BatchCompleted,

substrate/frame/vesting/src/lib.rs

@@ -172,9 +172,9 @@ decl_event!(
 	pub enum Event<T> where AccountId = <T as frame_system::Trait>::AccountId, Balance = BalanceOf<T> {
 		/// The amount vested has been updated. This could indicate more funds are available. The
 		/// balance given is the amount which is left unvested (and thus locked). 
-		/// [account, unvested]
+		/// \[account, unvested\]
 		VestingUpdated(AccountId, Balance),
-		/// An [account] has become fully vested. No further vesting can happen.
+		/// An \[account\] has become fully vested. No further vesting can happen.
 		VestingCompleted(AccountId),
 	}
 );