Documentation for assets module

srml/assets/src/lib.rs

@@ -14,7 +14,108 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
+//! # Assets Module
+//!
 //! A simple, secure module for dealing with fungible assets.
+//!
+//! ## Overview
+//!
+//! The Assets module provides functionality for asset management of fungible asset classes
+//! with a fixed supply, including:
+//!
+//! * Asset Issuance
+//! * Asset Transfer
+//! * Asset Destruction
+//!
+//! To use it in your runtime, you need to implement the assets [`Trait`](./trait.Trait.html).
+//!
+//! The supported dispatchable functions are documented in the [`Call`](./enum.Call.html) enum.
+//!
+//! ### Terminology
+//!
+//! * **Asset issuance:** The creation of a new asset, whose total supply will belong to the account that issues the asset.
+//! * **Asset transfer:** The action of transferring assets from one account to another.
+//! * **Asset destruction:** The process of an account removing its entire holding of an asset.
+//! * **Fungible asset:** An asset whose units are interchangeable.
+//! * **Non-fungible asset:** An asset for which each unit has unique characteristics.
+//!
+//! ### Goals
+//!
+//! The assets system in Substrate is designed to make the following possible:
+//!
+//! * Issue a unique asset to its creator's account.
+//! * Move assets between accounts.
+//! * Remove an account's balance of an asset when requested by that account's owner and update the asset's total supply.
+//!
+//! ## Interface
+//!
+//! ### Dispatchable Functions
+//!
+//! * `issue` - Issues the total supply of a new fungible asset to the account of the caller of the function.
+//! * `transfer` - Transfers an `amount` of units of fungible asset `id` from the balance of
+//! the function caller's account (`origin`) to a `target` account.
+//! * `destroy` - Destroys the entire holding of a fungible asset `id` associated with the account
+//! that called the function.
+//!
+//! Please refer to the [`Call`](./enum.Call.html) enum and its associated variants for documentation on each function.
+//!
+//! ### Public Functions
+//! <!-- Original author of descriptions: @gavofyork -->
+//!
+//! * `balance` - Get the asset `id` balance of `who`.
+//! * `total_supply` - Get the total supply of an asset `id`.
+//!
+//! Please refer to the [`Module`](./struct.Module.html) struct for details on publicly available functions.
+//!
+//! ## Usage
+//!
+//! The following example shows how to use the Assets module in your runtime by exposing public functions to:
+//!
+//! * Issue a new fungible asset for a token distribution event (airdrop).
+//! * Query the fungible asset holding balance of an account.
+//! * Query the total supply of a fungible asset that has been issued.
+//!
+//! ### Prerequisites
+//!
+//! Import the Assets module and types and derive your runtime's configuration traits from the Assets module trait.
+//!
+//! ### Simple Code Snippet
+//!
+//! ```rust,ignore
+//! use support::{decl_module, dispatch::Result};
+//! use system::ensure_signed;
+//!
+//! pub trait Trait: assets::Trait { }
+//!
+//! decl_module! {
+//! 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
+//! 		pub fn issue_token_airdrop(origin) -> Result {
+//! 			const ACCOUNT_ALICE: u64 = 1;
+//! 			const ACCOUNT_BOB: u64 = 2;
+//! 			const COUNT_AIRDROP_RECIPIENTS = 2;
+//! 			const TOKENS_FIXED_SUPPLY: u64 = 100;
+//!
+//! 			ensure!(!COUNT_AIRDROP_RECIPIENTS.is_zero(), "Divide by zero error.");
+//!
+//! 			let sender = ensure_signed(origin)?;
+//! 			let asset_id = Self::next_asset_id();
+//!
+//! 			<NextAssetId<T>>::mutate(|asset_id| *asset_id += 1);
+//! 			<Balances<T>>::insert((asset_id, &ACCOUNT_ALICE), TOKENS_FIXED_SUPPLY / COUNT_AIRDROP_RECIPIENTS);
+//! 			<Balances<T>>::insert((asset_id, &ACCOUNT_BOB), TOKENS_FIXED_SUPPLY / COUNT_AIRDROP_RECIPIENTS);
+//! 			<TotalSupply<T>>::insert(asset_id, TOKENS_FIXED_SUPPLY);
+//!
+//! 			Self::deposit_event(RawEvent::Issued(asset_id, sender, TOKENS_FIXED_SUPPLY));
+//! 			Ok(())
+//! 		}
+//! 	}
+//! }
+//! ```
+//!
+//! ## Related Modules
+//!
+//! * [`System`](../srml_system/index.html)
+//! * [`Support`](../srml_support/index.html)
 
 // Ensure we're `no_std` when compiling for Wasm.
 #![cfg_attr(not(feature = "std"), no_std)]
@@ -23,6 +124,7 @@ use srml_support::{StorageValue, StorageMap, Parameter, decl_module, decl_event,
 use primitives::traits::{Member, SimpleArithmetic, Zero, StaticLookup};
 use system::ensure_signed;
 
+/// The module configuration trait.
 pub trait Trait: system::Trait {
 	/// The overarching event type.
 	type Event: From<Event<Self>> + Into<<Self as system::Trait>::Event>;
@@ -34,7 +136,6 @@ pub trait Trait: system::Trait {
 type AssetId = u32;
 
 decl_module! {
-	// Simple declaration of the `Module` type. Lets the macro know what its working on.
 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
 		fn deposit_event<T>() = default;
 		/// Issue a new class of fungible assets. There are, and will only ever be, `total`
@@ -99,7 +200,7 @@ decl_storage! {
 		Balances: map (AssetId, T::AccountId) => T::Balance;
 		/// The next asset identifier up for grabs.
 		NextAssetId get(next_asset_id): AssetId;
-		/// The total unit supply of an asset
+		/// The total unit supply of an asset.
 		TotalSupply: map AssetId => T::Balance;
 	}
 }
@@ -113,7 +214,7 @@ impl<T: Trait> Module<T> {
 		<Balances<T>>::get((id, who))
 	}
 
-	// Get the total supply of an asset `id`
+	/// Get the total supply of an asset `id`.
 	pub fn total_supply(id: AssetId) -> T::Balance {
 		<TotalSupply<T>>::get(id)
 	}