Implement storage json metadata (#670)

* `decl_storage!` exposes json metadata about the storage

The metadata can be accessed by calling `store_json_metadata()`.

* Hide internal macros in the documentation

* Include the function documentation in the store json metadata

* Adapt the storage declarations to use doc comments

Author: bkchr

substrate/runtime-support/src/dispatch.rs

@@ -218,6 +218,7 @@ macro_rules! decl_dispatch {
 }
 
 #[macro_export]
+#[doc(hidden)]
 /// Implement a single dispatch modules to create a pairing of a dispatch trait and enum.
 macro_rules! __decl_dispatch_module_without_aux {
 	(
@@ -262,6 +263,7 @@ macro_rules! __decl_dispatch_module_without_aux {
 }
 
 #[macro_export]
+#[doc(hidden)]
 /// Implement a single dispatch modules to create a pairing of a dispatch trait and enum.
 macro_rules! __decl_dispatch_module_with_aux {
 	(
@@ -308,6 +310,7 @@ macro_rules! __decl_dispatch_module_with_aux {
 
 /// Implement a single dispatch modules to create a pairing of a dispatch trait and enum.
 #[macro_export]
+#[doc(hidden)]
 macro_rules! __decl_dispatch_module_common {
 	(
 		impl for $mod_type:ident<$trait_instance:ident: $trait_name:ident>;
@@ -419,6 +422,7 @@ macro_rules! __decl_dispatch_module_common {
 }
 
 #[macro_export]
+#[doc(hidden)]
 macro_rules! __impl_decode {
 	(
 		$input:expr;
@@ -452,6 +456,7 @@ macro_rules! __impl_decode {
 }
 
 #[macro_export]
+#[doc(hidden)]
 macro_rules! __impl_encode {
 	(
 		$dest:expr;
@@ -512,7 +517,7 @@ macro_rules! impl_outer_dispatch {
 				$camelcase ( $crate::dispatch::AuxCallableCallFor<$camelcase> )
 			,)*
 		}
-		impl_outer_dispatch_common! { $call_type, $($camelcase,)* }
+		__impl_outer_dispatch_common! { $call_type, $($camelcase,)* }
 		impl $crate::dispatch::AuxDispatchable for $call_type {
 			type Aux = $aux;
 			type Trait = $call_type;
@@ -552,7 +557,7 @@ macro_rules! impl_outer_dispatch {
 				$camelcase ( $crate::dispatch::CallableCallFor<$camelcase> )
 			,)*
 		}
-		impl_outer_dispatch_common! { $call_type, $($camelcase,)* }
+		__impl_outer_dispatch_common! { $call_type, $($camelcase,)* }
 		impl $crate::dispatch::Dispatchable for $call_type {
 			type Trait = $call_type;
 			fn dispatch(self) -> $crate::dispatch::Result {
@@ -580,7 +585,8 @@ macro_rules! impl_outer_dispatch {
 
 /// Implement a meta-dispatch module to dispatch to other dispatchers.
 #[macro_export]
-macro_rules! impl_outer_dispatch_common {
+#[doc(hidden)]
+macro_rules! __impl_outer_dispatch_common {
 	(
 		$call_type:ident, $( $camelcase:ident, )*
 	) => {
@@ -602,6 +608,7 @@ macro_rules! impl_outer_dispatch_common {
 
 /// Implement the `json_metadata` function.
 #[macro_export]
+#[doc(hidden)]
 macro_rules! __impl_json_metadata {
 	(
 		impl for $mod_type:ident<$trait_instance:ident: $trait_name:ident>;
@@ -618,6 +625,7 @@ macro_rules! __impl_json_metadata {
 
 /// Convert the list of calls into their JSON representation, joined by ",".
 #[macro_export]
+#[doc(hidden)]
 macro_rules! __calls_to_json {
 	// WITHOUT AUX
 	(
@@ -679,6 +687,7 @@ macro_rules! __calls_to_json {
 
 /// Convert a list of function into their JSON representation, joined by ",".
 #[macro_export]
+#[doc(hidden)]
 macro_rules! __functions_to_json {
 	// WITHOUT AUX
 	(
@@ -736,6 +745,7 @@ macro_rules! __functions_to_json {
 
 /// Convert a function into its JSON representation.
 #[macro_export]
+#[doc(hidden)]
 macro_rules! __function_to_json {
 	(
 		fn $fn_name:ident(
@@ -759,6 +769,7 @@ macro_rules! __function_to_json {
 
 /// Convert a function documentation attribute into its JSON representation.
 #[macro_export]
+#[doc(hidden)]
 macro_rules! __function_doc_to_json {
 	(
 		$prefix_str:tt;

substrate/runtime-support/src/lib.rs

@@ -38,6 +38,7 @@ extern crate serde_json;
 pub extern crate substrate_codec as codec;
 pub use self::storage::generator::Storage as GenericStorage;
 
+#[macro_use]
 pub mod dispatch;
 pub mod storage;
 mod hashable;

substrate/runtime-support/src/storage/generator.rs

@@ -161,55 +161,55 @@ impl<A, I> From<RawEvent<A, I>> for () {
 
 decl_storage! {
 	trait Store for Module<T: Trait> as Balances {
-		// The total amount of stake on the system.
+		/// The total amount of stake on the system.
 		pub TotalIssuance get(total_stake): required T::Balance;
-		// The minimum amount allowed to keep an account open.
+		/// The minimum amount allowed to keep an account open.
 		pub ExistentialDeposit get(existential_deposit): required T::Balance;
-		// The amount credited to a destination's account whose index was reclaimed.
+		/// The amount credited to a destination's account whose index was reclaimed.
 		pub ReclaimRebate get(reclaim_rebate): required T::Balance;
-		// The fee required to make a transfer.
+		/// The fee required to make a transfer.
 		pub TransferFee get(transfer_fee): required T::Balance;
-		// The fee required to create an account. At least as big as ReclaimRebate.
+		/// The fee required to create an account. At least as big as ReclaimRebate.
 		pub CreationFee get(creation_fee): required T::Balance;
 
-		// The next free enumeration set.
+		/// The next free enumeration set.
 		pub NextEnumSet get(next_enum_set): required T::AccountIndex;
-		// The enumeration sets.
+		/// The enumeration sets.
 		pub EnumSet get(enum_set): default map [ T::AccountIndex => Vec<T::AccountId> ];
 
-		// The "free" balance of a given account.
-		//
-		// This is the only balance that matters in terms of most operations on tokens. It is
-		// alone used to determine the balance when in the contract execution environment. When this
-		// balance falls below the value of `ExistentialDeposit`, then the "current account" is
-		// deleted: specifically `FreeBalance`. Furthermore, `OnFreeBalanceZero` callback
-		// is invoked, giving a chance to external modules to cleanup data associated with
-		// the deleted account.
-		//
-		// `system::AccountNonce` is also deleted if `ReservedBalance` is also zero (it also gets
-		// collapsed to zero if it ever becomes less than `ExistentialDeposit`.
+		/// The 'free' balance of a given account.
+		///
+		/// This is the only balance that matters in terms of most operations on tokens. It is
+		/// alone used to determine the balance when in the contract execution environment. When this
+		/// balance falls below the value of `ExistentialDeposit`, then the 'current account' is
+		/// deleted: specifically `FreeBalance`. Furthermore, `OnFreeBalanceZero` callback
+		/// is invoked, giving a chance to external modules to cleanup data associated with
+		/// the deleted account.
+		///
+		/// `system::AccountNonce` is also deleted if `ReservedBalance` is also zero (it also gets
+		/// collapsed to zero if it ever becomes less than `ExistentialDeposit`.
 		pub FreeBalance get(free_balance): default map [ T::AccountId => T::Balance ];
 
-		// The amount of the balance of a given account that is exterally reserved; this can still get
-		// slashed, but gets slashed last of all.
-		//
-		// This balance is a "reserve" balance that other subsystems use in order to set aside tokens
-		// that are still "owned" by the account holder, but which are unspendable. (This is different
-		// and wholly unrelated to the `Bondage` system used in the staking module.)
-		//
-		// When this balance falls below the value of `ExistentialDeposit`, then this "reserve account"
-		// is deleted: specifically, `ReservedBalance`.
-		//
-		// `system::AccountNonce` is also deleted if `FreeBalance` is also zero (it also gets
-		// collapsed to zero if it ever becomes less than `ExistentialDeposit`.
+		/// The amount of the balance of a given account that is exterally reserved; this can still get
+		/// slashed, but gets slashed last of all.
+		///
+		/// This balance is a 'reserve' balance that other subsystems use in order to set aside tokens
+		/// that are still 'owned' by the account holder, but which are unspendable. (This is different
+		/// and wholly unrelated to the `Bondage` system used in the staking module.)
+		///
+		/// When this balance falls below the value of `ExistentialDeposit`, then this 'reserve account'
+		/// is deleted: specifically, `ReservedBalance`.
+		///
+		/// `system::AccountNonce` is also deleted if `FreeBalance` is also zero (it also gets
+		/// collapsed to zero if it ever becomes less than `ExistentialDeposit`.
 		pub ReservedBalance get(reserved_balance): default map [ T::AccountId => T::Balance ];
 
 
 		// Payment stuff.
 
-		// The fee to be paid for making a transaction; the base.
+		/// The fee to be paid for making a transaction; the base.
 		pub TransactionBaseFee get(transaction_base_fee): required T::Balance;
-		// The fee to be paid for making a transaction; the per-byte portion.
+		/// The fee to be paid for making a transaction; the per-byte portion.
 		pub TransactionByteFee get(transaction_byte_fee): required T::Balance;
 	}
 }

substrate/runtime/balances/src/lib.rs

@@ -144,22 +144,22 @@ decl_module! {
 
 decl_storage! {
 	trait Store for Module<T: Trait> as Contract {
-		// The fee required to create a contract. At least as big as staking's ReclaimRebate.
+		/// The fee required to create a contract. At least as big as staking's ReclaimRebate.
 		ContractFee get(contract_fee): required T::Balance;
-		// The fee charged for a call into a contract.
+		/// The fee charged for a call into a contract.
 		CallBaseFee get(call_base_fee): required T::Gas;
-		// The fee charged for a create of a contract.
+		/// The fee charged for a create of a contract.
 		CreateBaseFee get(create_base_fee): required T::Gas;
-		// The price of one unit of gas.
+		/// The price of one unit of gas.
 		GasPrice get(gas_price): required T::Balance;
-		// The maximum nesting level of a call/create stack.
+		/// The maximum nesting level of a call/create stack.
 		MaxDepth get(max_depth): required u32;
-		// The maximum amount of gas that could be expended per block.
+		/// The maximum amount of gas that could be expended per block.
 		BlockGasLimit get(block_gas_limit): required T::Gas;
-		// Gas spent so far in this block.
+		/// Gas spent so far in this block.
 		GasSpent get(gas_spent): default T::Gas;
 
-		// The code associated with an account.
+		/// The code associated with an account.
 		pub CodeOf: default map [ T::AccountId => Vec<u8> ];	// TODO Vec<u8> values should be optimised to not do a length prefix.
 	}
 }

substrate/runtime/contract/src/lib.rs

@@ -130,53 +130,53 @@ decl_storage! {
 	trait Store for Module<T: Trait> as Council {
 
 		// parameters
-		// How much should be locked up in order to submit one's candidacy.
+		/// How much should be locked up in order to submit one's candidacy.
 		pub CandidacyBond get(candidacy_bond): required T::Balance;
-		// How much should be locked up in order to be able to submit votes.
+		/// How much should be locked up in order to be able to submit votes.
 		pub VotingBond get(voting_bond): required T::Balance;
-		// The punishment, per voter, if you provide an invalid presentation.
+		/// The punishment, per voter, if you provide an invalid presentation.
 		pub PresentSlashPerVoter get(present_slash_per_voter): required T::Balance;
-		// How many runners-up should have their approvals persist until the next vote.
+		/// How many runners-up should have their approvals persist until the next vote.
 		pub CarryCount get(carry_count): required u32;
-		// How long to give each top candidate to present themselves after the vote ends.
+		/// How long to give each top candidate to present themselves after the vote ends.
 		pub PresentationDuration get(presentation_duration): required T::BlockNumber;
-		// How many votes need to go by after a voter's last vote before they can be reaped if their
-		// approvals are moot.
+		/// How many votes need to go by after a voter's last vote before they can be reaped if their
+		/// approvals are moot.
 		pub InactiveGracePeriod get(inactivity_grace_period): required VoteIndex;
-		// How often (in blocks) to check for new votes.
+		/// How often (in blocks) to check for new votes.
 		pub VotingPeriod get(voting_period): required T::BlockNumber;
-		// How long each position is active for.
+		/// How long each position is active for.
 		pub TermDuration get(term_duration): required T::BlockNumber;
-		// Number of accounts that should be sitting on the council.
+		/// Number of accounts that should be sitting on the council.
 		pub DesiredSeats get(desired_seats): required u32;
 
 		// permanent state (always relevant, changes only at the finalisation of voting)
-		// The current council. When there's a vote going on, this should still be used for executive
-		// matters.
+		/// The current council. When there's a vote going on, this should still be used for executive
+		/// matters.
 		pub ActiveCouncil get(active_council): default Vec<(T::AccountId, T::BlockNumber)>;
-		// The total number of votes that have happened or are in progress.
+		/// The total number of votes that have happened or are in progress.
 		pub VoteCount get(vote_index): default VoteIndex;
 
 		// persistent state (always relevant, changes constantly)
-		// The last cleared vote index that this voter was last active at.
+		/// The last cleared vote index that this voter was last active at.
 		pub ApprovalsOf get(approvals_of): default map [ T::AccountId => Vec<bool> ];
-		// The vote index and list slot that the candidate `who` was registered or `None` if they are not
-		// currently registered.
+		/// The vote index and list slot that the candidate `who` was registered or `None` if they are not
+		/// currently registered.
 		pub RegisterInfoOf get(candidate_reg_info): map [ T::AccountId => (VoteIndex, u32) ];
-		// The last cleared vote index that this voter was last active at.
+		/// The last cleared vote index that this voter was last active at.
 		pub LastActiveOf get(voter_last_active): map [ T::AccountId => VoteIndex ];
-		// The present voter list.
+		/// The present voter list.
 		pub Voters get(voters): default Vec<T::AccountId>;
-		// The present candidate list.
+		/// The present candidate list.
 		pub Candidates get(candidates): default Vec<T::AccountId>; // has holes
 		pub CandidateCount get(candidate_count): default u32;
 
 		// temporary state (only relevant during finalisation/presentation)
-		// The accounts holding the seats that will become free on the next tally.
+		/// The accounts holding the seats that will become free on the next tally.
 		pub NextFinalise get(next_finalise): (T::BlockNumber, u32, Vec<T::AccountId>);
-		// The stakes as they were at the point that the vote ended.
+		/// The stakes as they were at the point that the vote ended.
 		pub SnapshotedStakes get(snapshoted_stakes): required Vec<T::Balance>;
-		// Get the leaderboard if we;re in the presentation phase.
+		/// Get the leaderboard if we;re in the presentation phase.
 		pub Leaderboard get(leaderboard): Vec<(T::Balance, T::AccountId)>; // ORDERED low -> high
 	}
 }

substrate/runtime/council/src/lib.rs

@@ -82,31 +82,31 @@ decl_module! {
 decl_storage! {
 	trait Store for Module<T: Trait> as Democracy {
 
-		// The number of (public) proposals that have been made so far.
+		/// The number of (public) proposals that have been made so far.
 		pub PublicPropCount get(public_prop_count): default PropIndex;
-		// The public proposals. Unsorted.
+		/// The public proposals. Unsorted.
 		pub PublicProps get(public_props): default Vec<(PropIndex, T::Proposal, T::AccountId)>;
-		// Those who have locked a deposit.
+		/// Those who have locked a deposit.
 		pub DepositOf get(deposit_of): map [ PropIndex => (T::Balance, Vec<T::AccountId>) ];
-		// How often (in blocks) new public referenda are launched.
+		/// How often (in blocks) new public referenda are launched.
 		pub LaunchPeriod get(launch_period): required T::BlockNumber;
-		// The minimum amount to be used as a deposit for a public referendum proposal.
+		/// The minimum amount to be used as a deposit for a public referendum proposal.
 		pub MinimumDeposit get(minimum_deposit): required T::Balance;
 
-		// How often (in blocks) to check for new votes.
+		/// How often (in blocks) to check for new votes.
 		pub VotingPeriod get(voting_period): required T::BlockNumber;
 
-		// The next free referendum index, aka the number of referendums started so far.
+		/// The next free referendum index, aka the number of referendums started so far.
 		pub ReferendumCount get(referendum_count): required ReferendumIndex;
-		// The next referendum index that should be tallied.
+		/// The next referendum index that should be tallied.
 		pub NextTally get(next_tally): required ReferendumIndex;
-		// Information concerning any given referendum.
+		/// Information concerning any given referendum.
 		pub ReferendumInfoOf get(referendum_info): map [ ReferendumIndex => (T::BlockNumber, T::Proposal, VoteThreshold) ];
 
-		// Get the voters for the current proposal.
+		/// Get the voters for the current proposal.
 		pub VotersFor get(voters_for): default map [ ReferendumIndex => Vec<T::AccountId> ];
 
-		// Get the vote, if Some, of `who`.
+		/// Get the vote, if Some, of `who`.
 		pub VoteOf get(vote_of): map [ (ReferendumIndex, T::AccountId) => bool ];
 	}
 }

substrate/runtime/democracy/src/lib.rs

@@ -105,23 +105,23 @@ impl<N> From<RawEvent<N>> for () {
 decl_storage! {
 	trait Store for Module<T: Trait> as Session {
 
-		// The current set of validators.
+		/// The current set of validators.
 		pub Validators get(validators): required Vec<T::AccountId>;
-		// Current length of the session.
+		/// Current length of the session.
 		pub SessionLength get(length): required T::BlockNumber;
-		// Current index of the session.
+		/// Current index of the session.
 		pub CurrentIndex get(current_index): required T::BlockNumber;
-		// Timestamp when current session started.
+		/// Timestamp when current session started.
 		pub CurrentStart get(current_start): required T::Moment;
 
-		// New session is being forced is this entry exists; in which case, the boolean value is whether
-		// the new session should be considered a normal rotation (rewardable) or exceptional (slashable).
+		/// New session is being forced is this entry exists; in which case, the boolean value is whether
+		/// the new session should be considered a normal rotation (rewardable) or exceptional (slashable).
 		pub ForcingNewSession get(forcing_new_session): bool;
-		// Block at which the session length last changed.
+		/// Block at which the session length last changed.
 		LastLengthChange: T::BlockNumber;
-		// The next key for a given validator.
+		/// The next key for a given validator.
 		NextKeyFor: map [ T::AccountId => T::SessionKey ];
-		// The next session length.
+		/// The next session length.
 		NextSessionLength: T::BlockNumber;
 	}
 }