From f6d7400e2cb8e0012e85883732d278e267413ce2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20K=C3=B6cher?= Date: Wed, 5 Sep 2018 17:41:14 +0200 Subject: [PATCH] Adapt the storage declarations to use doc comments --- substrate/runtime/balances/src/lib.rs | 64 +++++++++++++------------- substrate/runtime/contract/src/lib.rs | 16 +++---- substrate/runtime/council/src/lib.rs | 44 +++++++++--------- substrate/runtime/democracy/src/lib.rs | 22 ++++----- substrate/runtime/session/src/lib.rs | 18 ++++---- substrate/runtime/staking/src/lib.rs | 38 +++++++-------- substrate/runtime/system/src/lib.rs | 2 +- substrate/runtime/timestamp/src/lib.rs | 4 +- substrate/runtime/treasury/src/lib.rs | 18 ++++---- 9 files changed, 113 insertions(+), 113 deletions(-) diff --git a/substrate/runtime/balances/src/lib.rs b/substrate/runtime/balances/src/lib.rs index 5eeb0007c206b..46317cb1c64f4 100644 --- a/substrate/runtime/balances/src/lib.rs +++ b/substrate/runtime/balances/src/lib.rs @@ -161,55 +161,55 @@ impl From> for () { decl_storage! { trait Store for Module 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 ]; - // 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; } } diff --git a/substrate/runtime/contract/src/lib.rs b/substrate/runtime/contract/src/lib.rs index c0b3cb045534d..6092787cfddb9 100644 --- a/substrate/runtime/contract/src/lib.rs +++ b/substrate/runtime/contract/src/lib.rs @@ -144,22 +144,22 @@ decl_module! { decl_storage! { trait Store for Module 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 ]; // TODO Vec values should be optimised to not do a length prefix. } } diff --git a/substrate/runtime/council/src/lib.rs b/substrate/runtime/council/src/lib.rs index c6ee841fed1d5..8672a581fe2c8 100644 --- a/substrate/runtime/council/src/lib.rs +++ b/substrate/runtime/council/src/lib.rs @@ -130,53 +130,53 @@ decl_storage! { trait Store for Module 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 ]; - // 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; - // The present candidate list. + /// The present candidate list. pub Candidates get(candidates): default Vec; // 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); - // 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; - // 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 } } diff --git a/substrate/runtime/democracy/src/lib.rs b/substrate/runtime/democracy/src/lib.rs index 046df66bfae07..b68c072d15ba2 100644 --- a/substrate/runtime/democracy/src/lib.rs +++ b/substrate/runtime/democracy/src/lib.rs @@ -82,31 +82,31 @@ decl_module! { decl_storage! { trait Store for Module 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) ]; - // 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 ]; - // Get the vote, if Some, of `who`. + /// Get the vote, if Some, of `who`. pub VoteOf get(vote_of): map [ (ReferendumIndex, T::AccountId) => bool ]; } } diff --git a/substrate/runtime/session/src/lib.rs b/substrate/runtime/session/src/lib.rs index 5428d960b1ac7..b155053fe49ab 100644 --- a/substrate/runtime/session/src/lib.rs +++ b/substrate/runtime/session/src/lib.rs @@ -105,23 +105,23 @@ impl From> for () { decl_storage! { trait Store for Module as Session { - // The current set of validators. + /// The current set of validators. pub Validators get(validators): required Vec; - // 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; } } diff --git a/substrate/runtime/staking/src/lib.rs b/substrate/runtime/staking/src/lib.rs index abaaa994dbb59..4242fa01e152d 100644 --- a/substrate/runtime/staking/src/lib.rs +++ b/substrate/runtime/staking/src/lib.rs @@ -145,47 +145,47 @@ impl From> for () { decl_storage! { trait Store for Module as Staking { - // The ideal number of staking participants. + /// The ideal number of staking participants. pub ValidatorCount get(validator_count): required u32; - // Minimum number of staking participants before emergency conditions are imposed. + /// Minimum number of staking participants before emergency conditions are imposed. pub MinimumValidatorCount: u32; - // The length of a staking era in sessions. + /// The length of a staking era in sessions. pub SessionsPerEra get(sessions_per_era): required T::BlockNumber; - // Maximum reward, per validator, that is provided per acceptable session. + /// Maximum reward, per validator, that is provided per acceptable session. pub SessionReward get(session_reward): required T::Balance; - // Slash, per validator that is taken per abnormal era end. + /// Slash, per validator that is taken per abnormal era end. pub EarlyEraSlash get(early_era_slash): required T::Balance; - // Number of instances of offline reports before slashing begins for validators. + /// Number of instances of offline reports before slashing begins for validators. pub OfflineSlashGrace get(offline_slash_grace): default u32; - // The length of the bonding duration in blocks. + /// The length of the bonding duration in blocks. pub BondingDuration get(bonding_duration): required T::BlockNumber; - // The current era index. + /// The current era index. pub CurrentEra get(current_era): required T::BlockNumber; - // Preferences that a validator has. + /// Preferences that a validator has. pub ValidatorPreferences get(validator_preferences): default map [ T::AccountId => ValidatorPrefs ]; - // All the accounts with a desire to stake. + /// All the accounts with a desire to stake. pub Intentions get(intentions): default Vec; - // All nominator -> nominee relationships. + /// All nominator -> nominee relationships. pub Nominating get(nominating): map [ T::AccountId => T::AccountId ]; - // Nominators for a particular account. + /// Nominators for a particular account. pub NominatorsFor get(nominators_for): default map [ T::AccountId => Vec ]; - // Nominators for a particular account that is in action right now. + /// Nominators for a particular account that is in action right now. pub CurrentNominatorsFor get(current_nominators_for): default map [ T::AccountId => Vec ]; - // The next value of sessions per era. + /// The next value of sessions per era. pub NextSessionsPerEra get(next_sessions_per_era): T::BlockNumber; - // The session index at which the era length last changed. + /// The session index at which the era length last changed. pub LastEraLengthChange get(last_era_length_change): default T::BlockNumber; - // The current era stake threshold - unused at present. Consider for removal. + /// The current era stake threshold - unused at present. Consider for removal. pub StakeThreshold get(stake_threshold): required T::Balance; - // The block at which the `who`'s funds become entirely liquid. + /// The block at which the `who`'s funds become entirely liquid. pub Bondage get(bondage): default map [ T::AccountId => T::BlockNumber ]; - // The number of times a given validator has been reported offline. This gets decremented by one each era that passes. + /// The number of times a given validator has been reported offline. This gets decremented by one each era that passes. pub SlashCount get(slash_count): default map [ T::AccountId => u32 ]; - // We are forcing a new era. + /// We are forcing a new era. pub ForcingNewEra get(forcing_new_era): (); } } diff --git a/substrate/runtime/system/src/lib.rs b/substrate/runtime/system/src/lib.rs index 617852b35d313..4f691c89afde9 100644 --- a/substrate/runtime/system/src/lib.rs +++ b/substrate/runtime/system/src/lib.rs @@ -136,7 +136,7 @@ decl_storage! { pub ExtrinsicIndex get(extrinsic_index): u32; ExtrinsicData get(extrinsic_data): required map [ u32 => Vec ]; RandomSeed get(random_seed): required T::Hash; - // The current block number being processed. Set by `execute_block`. + /// The current block number being processed. Set by `execute_block`. Number get(block_number): required T::BlockNumber; ParentHash get(parent_hash): required T::Hash; ExtrinsicsRoot get(extrinsics_root): required T::Hash; diff --git a/substrate/runtime/timestamp/src/lib.rs b/substrate/runtime/timestamp/src/lib.rs index ae30500d0162d..b8938e7e198f9 100644 --- a/substrate/runtime/timestamp/src/lib.rs +++ b/substrate/runtime/timestamp/src/lib.rs @@ -63,10 +63,10 @@ decl_module! { decl_storage! { trait Store for Module as Timestamp { pub Now get(now): required T::Moment; - // The minimum (and advised) period between blocks. + /// The minimum (and advised) period between blocks. pub BlockPeriod get(block_period): required T::Moment; - // Did the timestamp get updated in this block? + /// Did the timestamp get updated in this block? DidUpdate: default bool; } } diff --git a/substrate/runtime/treasury/src/lib.rs b/substrate/runtime/treasury/src/lib.rs index 919ebb43c47c3..c6ddd21c8ad49 100644 --- a/substrate/runtime/treasury/src/lib.rs +++ b/substrate/runtime/treasury/src/lib.rs @@ -122,31 +122,31 @@ decl_storage! { trait Store for Module as Treasury { // Config... - // Proportion of funds that should be bonded in order to place a proposal. An accepted - // proposal gets these back. A rejected proposal doesn't. + /// Proportion of funds that should be bonded in order to place a proposal. An accepted + /// proposal gets these back. A rejected proposal doesn't. ProposalBond get(proposal_bond): required Permill; - // Minimum amount of funds that should be placed ina deposit for making a proposal. + /// Minimum amount of funds that should be placed ina deposit for making a proposal. ProposalBondMinimum get(proposal_bond_minimum): required T::Balance; - // Period between successive spends. + /// Period between successive spends. SpendPeriod get(spend_period): required T::BlockNumber; - // Percentage of spare funds (if any) that are burnt per spend period. + /// Percentage of spare funds (if any) that are burnt per spend period. Burn get(burn): required Permill; // State... - // Total funds available to this module for spending. + /// Total funds available to this module for spending. Pot get(pot): default T::Balance; - // Number of proposals that have been made. + /// Number of proposals that have been made. ProposalCount get(proposal_count): default ProposalIndex; - // Proposals that have been made. + /// Proposals that have been made. Proposals get(proposals): map [ ProposalIndex => Proposal ]; - // Proposal indices that have been approved but not yet awarded. + /// Proposal indices that have been approved but not yet awarded. Approvals get(approvals): default Vec; } }