diff --git a/substrate/frame/aura/src/lib.rs b/substrate/frame/aura/src/lib.rs
index 1a711f314abcdee5d7fa4c15f1c652741f71dccd..e2aafde9efe6ef699bcd61ef861fe7104dd7e331 100644
--- a/substrate/frame/aura/src/lib.rs
+++ b/substrate/frame/aura/src/lib.rs
@@ -33,8 +33,6 @@
 //!
 //! - [Timestamp](../pallet_timestamp/index.html): The Timestamp module is used in Aura to track
 //! consensus rounds (via `slots`).
-//! - [Consensus](../frame_consensus/index.html): The Consensus module does not relate directly to Aura,
-//!  but serves to manage offline reporting by implementing `ProvideInherent` in a similar way.
 //!
 //! ## References
 //!
diff --git a/substrate/frame/session/src/lib.rs b/substrate/frame/session/src/lib.rs
index 098b5330779effdfd09c792b4dce329c4d9f4406..f98e334cbb018072ed2caecb95f87b2270b20075 100644
--- a/substrate/frame/session/src/lib.rs
+++ b/substrate/frame/session/src/lib.rs
@@ -30,92 +30,72 @@
 //!
 //! - **Session:** A session is a period of time that has a constant set of validators. Validators can only join
 //! or exit the validator set at a session change. It is measured in block numbers. The block where a session is
-//! ended is determined by the `ShouldSessionEnd` trait. When the session is ending, a new validator set
+//! ended is determined by the `ShouldEndSession` trait. When the session is ending, a new validator set
 //! can be chosen by `OnSessionEnding` implementations.
 //! - **Session key:** A session key is actually several keys kept together that provide the various signing
 //! functions required by network authorities/validators in pursuit of their duties.
 //! - **Validator ID:** Every account has an associated validator ID. For some simple staking systems, this
 //! may just be the same as the account ID. For staking systems using a stash/controller model,
 //! the validator ID would be the stash account ID of the controller.
-//! - **Session key configuration process:** A session key is set using `set_key` for use in the
-//! next session. It is stored in `NextKeyFor`, a mapping between the caller's `ValidatorId` and the session
-//! keys provided. `set_key` allows users to set their session key prior to being selected as validator.
+//! - **Session key configuration process:** Session keys are set using `set_keys` for use not in
+//! the next session, but the session after next. They are stored in `NextKeys`, a mapping between
+//! the caller's `ValidatorId` and the session keys provided. `set_keys` allows users to set their
+//! session key prior to being selected as validator.
 //! It is a public call since it uses `ensure_signed`, which checks that the origin is a signed account.
-//! As such, the account ID of the origin stored in in `NextKeyFor` may not necessarily be associated with
+//! As such, the account ID of the origin stored in `NextKeys` may not necessarily be associated with
 //! a block author or a validator. The session keys of accounts are removed once their account balance is zero.
-//! - **Validator set session key configuration process:** Each session we iterate through the current
-//! set of validator account IDs to check if a session key was created for it in the previous session
-//! using `set_key`. If it was then we call `set_authority` from the [Consensus module](../frame_consensus/index.html)
-//! and pass it a set of session keys (each associated with an account ID) as the session keys for the new
-//! validator set. Lastly, if the session key of the current authority does not match any session keys stored under
-//! its validator index in the `AuthorityStorageVec` mapping, then we update the mapping with its session
-//! key and update the saved list of original authorities if necessary
-//! (see https://github.com/paritytech/substrate/issues/1290). Note: Authorities are stored in the Consensus module.
-//! They are represented by a validator account ID index from the Session module and allocated with a session
-//! key for the length of the session.
-//! - **Session length change process:** At the start of the next session we allocate a session index and record the
-//! timestamp when the session started. If a `NextSessionLength` was recorded in the previous session, we record
-//! it as the new session length. Additionally, if the new session length differs from the length of the
-//! next session then we record a `LastLengthChange`.
+//! - **Session length:** This pallet does not assume anything about the length of each session.
+//! Rather, it relies on an implementation of `ShouldEndSession` to dictate a new session's start.
+//! This pallet provides the `PeriodicSessions` struct for simple periodic sessions.
 //! - **Session rotation configuration:** Configure as either a 'normal' (rewardable session where rewards are
 //! applied) or 'exceptional' (slashable) session rotation.
-//! - **Session rotation process:** The session is changed at the end of the final block of the current session
-//! using the `on_finalize` method. It may be called by either an origin or internally from another runtime
-//! module at the end of each block.
+//! - **Session rotation process:** At the beginning of each block, the `on_initialize` function
+//! queries the provided implementation of `ShouldEndSession`. If the session is to end the newly
+//! activated validator IDs and session keys are taken from storage and passed to the
+//! `SessionHandler`. The validator set supplied by `SessionManager::new_session` and the corresponding session
+//! keys, which may have been registered via `set_keys` during the previous session, are written
+//! to storage where they will wait one session before being passed to the `SessionHandler`
+//! themselves.
 //!
 //! ### Goals
 //!
-//! The Session module in Substrate is designed to make the following possible:
+//! The Session pallet is designed to make the following possible:
 //!
-//! - Set session keys of the validator set for the next session.
-//! - Set the length of a session.
+//! - Set session keys of the validator set for upcoming sessions.
+//! - Control the length of sessions.
 //! - Configure and switch between either normal or exceptional session rotations.
 //!
 //! ## Interface
 //!
 //! ### Dispatchable Functions
 //!
-//! - `set_key` - Set a validator's session key for the next session.
-//! - `set_length` - Set a new session length to be applied upon the next session change.
-//! - `force_new_session` - Force a new session that should be considered either a normal (rewardable)
-//! or exceptional rotation.
-//! - `on_finalize` - Called when a block is finalized. Will rotate session if it is the last
-//! block of the current session.
+//! - `set_keys` - Set a validator's session keys for upcoming sessions.
 //!
 //! ### Public Functions
 //!
-//! - `validator_count` - Get the current number of validators.
-//! - `last_length_change` - Get the block number when the session length last changed.
-//! - `apply_force_new_session` - Force a new session. Can be called by other runtime modules.
-//! - `set_validators` - Set the current set of validators. Can only be called by the Staking module.
-//! - `check_rotate_session` - Rotate the session and apply rewards if necessary. Called after the Staking
-//! module updates the authorities to the new validator set.
-//! - `rotate_session` - Change to the next session. Register the new authority set. Update session keys.
-//! Enact session length change if applicable.
-//! - `ideal_session_duration` - Get the time of an ideal session.
-//! - `blocks_remaining` - Get the number of blocks remaining in the current session,
-//! excluding the current block.
+//! - `rotate_session` - Change to the next session. Register the new authority set. Queue changes
+//! for next session rotation.
+//! - `disable_index` - Disable a validator by index.
+//! - `disable` - Disable a validator by Validator ID
 //!
 //! ## Usage
 //!
 //! ### Example from the SRML
 //!
-//! The [Staking module](../pallet_staking/index.html) uses the Session module to get the validator set.
+//! The [Staking pallet](../pallet_staking/index.html) uses the Session pallet to get the validator set.
 //!
 //! ```
 //! use pallet_session as session;
-//! # fn not_executed<T: session::Trait>() {
 //!
-//! let validators = <session::Module<T>>::validators();
-//! # }
+//! fn validators<T: pallet_session::Trait>() -> Vec<<T as pallet_session::Trait>::ValidatorId> {
+//!	<pallet_session::Module<T>>::validators()
+//! }
 //! # fn main(){}
 //! ```
 //!
 //! ## Related Modules
 //!
-//! - [Consensus](../frame_consensus/index.html)
 //! - [Staking](../pallet_staking/index.html)
-//! - [Timestamp](../pallet_timestamp/index.html)
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -478,7 +458,7 @@ decl_module! {
 
 		fn deposit_event() = default;
 
-		/// Sets the session key(s) of the function caller to `key`.
+		/// Sets the session key(s) of the function caller to `keys`.
 		/// Allows an account to set its session key prior to becoming a validator.
 		/// This doesn't take effect until the next session.
 		///
diff --git a/substrate/frame/sudo/src/lib.rs b/substrate/frame/sudo/src/lib.rs
index e49596b4bdb9bda1d2f676c31be978c8f884ac1a..ea436e2629b496c8acdfd8598b8232fbdb478634 100644
--- a/substrate/frame/sudo/src/lib.rs
+++ b/substrate/frame/sudo/src/lib.rs
@@ -77,7 +77,6 @@
 //!
 //! ## Related Modules
 //!
-//! * [Consensus](../frame_consensus/index.html)
 //! * [Democracy](../pallet_democracy/index.html)
 //!
 //! [`Call`]: ./enum.Call.html