grandpa: add some more docs

frame/grandpa/src/equivocation.rs

@@ -29,6 +29,12 @@
 //! And in a runtime context, so that the GRANDPA module can validate the
 //! equivocation proofs in the extrinsic and report the offences.
 //!
+//! IMPORTANT:
+//! When using this module for enabling equivocation reporting it is required
+//! that the `ValidateEquivocationReport` signed extension is used in the runtime
+//! definition. Failure to do so will allow invalid equivocation reports to be
+//! accepted by the runtime.
+//!
 
 use sp_std::prelude::*;
 

frame/grandpa/src/lib.rs

@@ -228,8 +228,9 @@ decl_module! {
 		/// against the extracted offender. If both are valid, the offence
 		/// will be reported.
 		///
-		/// Since the weight is 0 in order to avoid DoS pre-validation is implemented in a
-		/// `SignedExtension`.
+		/// Since the weight of the extrinsic is 0, in order to avoid DoS by
+		/// submission of invalid equivocation reports, a mandatory pre-validation of
+		/// the extrinsic is implemented in a `SignedExtension`.
 		#[weight = 0]
 		fn report_equivocation(
 			origin,
@@ -440,9 +441,9 @@ impl<T: Trait> Module<T> {
 			Self::set_grandpa_authorities(authorities);
 		}
 
-		// NOTE: initialize first session of first set. this is necessary
-		// because we only update this `on_new_session` which isn't called
-		// for the genesis session.
+		// NOTE: initialize first session of first set. this is necessary for
+		// the genesis set and session since we only update the set -> session
+		// mapping whenever a new session starts, i.e. through `on_new_session`.
 		SetIdSession::insert(0, 0);
 	}
 

primitives/finality-grandpa/src/lib.rs

@@ -491,7 +491,10 @@ sp_api::decl_runtime_apis! {
 		/// provide the equivocation proof and a key ownership proof (should be
 		/// obtained using `generate_key_ownership_proof`). This method will
 		/// sign the extrinsic with any reporting keys available in the keystore
-		/// and will push the transaction to the pool.
+		/// and will push the transaction to the pool. This method returns `None`
+		/// when creation of the extrinsic fails, either due to unavailability
+		/// of keys to sign, or because equivocation reporting is disabled for
+		/// the given runtime (i.e. this method is hardcoded to return `None`).
 		/// Only useful in an offchain context.
 		fn submit_report_equivocation_extrinsic(
 			equivocation_proof: EquivocationProof<Block::Hash, NumberFor<Block>>,