Add documentation to the Sudo module (#2017)

* First draft of sudo module documentation

* add ignore tags to code blocks

* Suggested Updates

Still needs some more love with links

* Update lib.rs

* Add links to other modules

* Update lib.rs

* style

* missed parens

substrate/srml/sudo/src/lib.rs

@@ -14,8 +14,113 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
-//! The Example: A simple example of a runtime module demonstrating
-//! concepts, APIs and structures common to most runtime modules.
+//! # Sudo Module
+//!
+//! ## Overview
+//!
+//! The sudo module allows for a single account (called the "sudo key")
+//! to execute dispatchable functions that require a `Root` call
+//! or designate a new account to replace them as the sudo key.
+//! Only one account can be the sudo key at a time.
+//!
+//! You can start using the sudo module by implementing the sudo [`Trait`].
+//!
+//! Supported dispatchable functions are documented in the [`Call`] enum.
+//!
+//! ## Interface
+//!
+//! ### Dispatchable Functions
+//!
+//! Only the sudo key can call the dispatchable functions from the sudo module.
+//!
+//! * `sudo` - Make a `Root` call to a dispatchable function.
+//! * `set_key` - Assign a new account to be the sudo key.
+//!
+//! Please refer to the [`Call`] enum and its associated variants for documentation on each function.
+//!
+//! ## Usage
+//!
+//! ### Prerequisites
+//!
+//! To use the sudo module in your runtime, you must implement the following trait in your runtime:
+//!
+//! ```ignore
+//! impl sudo::Trait for Runtime {
+//! 	type Event = Event;
+//! 	type Proposal = Call;
+//! }
+//! ```
+//!
+//! You can then import the Sudo module in your `construct_runtime!` macro with:
+//!
+//! ```ignore
+//! Sudo: sudo,
+//! ```
+//!
+//! ### Executing Privileged Functions
+//!
+//! The sudo module itself is not intended to be used within other modules.
+//! Instead, you can build "privileged functions" in other modules that require `Root` origin.
+//! You can execute these privileged functions by calling `sudo` with the sudo key account.
+//! Privileged functions cannot be directly executed via an extrinsic.
+//!
+//! Learn more about privileged functions and `Root` origin in the [`Origin`] type documentation.
+//!
+//! ### Simple Code Snippet
+//!
+//! This is an example of a module that exposes a privileged function:
+//!
+//! ```ignore
+//! use support::{decl_module, dispatch::Result};
+//! use system::ensure_root;
+//!
+//! pub trait Trait: system::Trait {}
+//!
+//! decl_module! {
+//!     pub struct Module<T: Trait> for enum Call where origin: T::Origin {
+//!         pub fn privileged_function(origin) -> Result {
+//!             ensure_root(origin)?;
+//!
+//!             // do something...
+//!
+//!             Ok(())
+//!         }
+//!     }
+//! }
+//! ```
+//!
+//! ### Example from SRML
+//!
+//! The consensus module exposes a `set_code` privileged function
+//! that allows you to set the on-chain Wasm runtime code:
+//!
+//! ```ignore
+//! /// Set the new code.
+//! pub fn set_code(new: Vec<u8>) {
+//!     storage::unhashed::put_raw(well_known_keys::CODE, &new);
+//! }
+//! ```
+//!
+//! ## Genesis Config
+//!
+//! To use the sudo module, you need to set an initial superuser account as the sudo `key`.
+//!
+//! ```ignore
+//! GenesisConfig {
+//!     sudo: Some(SudoConfig {
+//!         key: AccountId,
+//!     })
+//! }
+//! ```
+//!
+//! ## Related Modules
+//!
+//! * [Consensus](../srml_consensus/index.html)
+//! * [Democracy](../srml_democracy/index.html)
+//!
+//! [`Call`]: ./enum.Call.html
+//! [`Trait`]: ./trait.Trait.html
+//! [`Origin`]: https://docs.substrate.dev/docs/substrate-types
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -33,10 +138,13 @@ pub trait Trait: system::Trait {
 }
 
 decl_module! {
-	// Simple declaration of the `Module` type. Lets the macro know what its working on.
+	// Simple declaration of the `Module` type. Lets the macro know what it's working on.
 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
 		fn deposit_event<T>() = default;
 
+		/// Authenticates the sudo key and dispatches a function call with `Root` origin.
+		///
+		/// The dispatch origin for this call must be _Signed_.
 		fn sudo(origin, proposal: Box<T::Proposal>) {
 			// This is a public call, so we ensure that the origin is some signed account.
 			let sender = ensure_signed(origin)?;
@@ -46,6 +154,9 @@ decl_module! {
 			Self::deposit_event(RawEvent::Sudid(ok));
 		}
 
+		/// Authenticates the current sudo key and sets the given AccountId (`new`) as the new sudo key.
+		///
+		/// The dispatch origin for this call must be _Signed_.
 		fn set_key(origin, new: <T::Lookup as StaticLookup>::Source) {
 			// This is a public call, so we ensure that the origin is some signed account.
 			let sender = ensure_signed(origin)?;
@@ -69,6 +180,7 @@ decl_event!(
 
 decl_storage! {
 	trait Store for Module<T: Trait> as Sudo {
+		/// The `AccountId` of the sudo key.
 		Key get(key) config(): T::AccountId;
 	}
 }