diff --git a/contracts/eosio.bios/include/eosio.bios/eosio.bios.hpp b/contracts/eosio.bios/include/eosio.bios/eosio.bios.hpp index 7c91ddafd..7db861300 100644 --- a/contracts/eosio.bios/include/eosio.bios/eosio.bios.hpp +++ b/contracts/eosio.bios/include/eosio.bios/eosio.bios.hpp @@ -75,12 +75,10 @@ namespace eosiobios { public: using contract::contract; /** - * New account action - * - * @details Called after a new account is created. This code enforces resource-limits rules + * \details New account action, it is called after a new account is created. This code enforces resource-limits rules * for new accounts as well as new account naming conventions. * - * 1. accounts cannot contain '.' symbols which forces all acccounts to be 12 + * 1. accounts cannot contain '.' symbols which forces all accounts to be 12 * characters long without '.' until a future account auction process is implemented * which prevents name squatting. * @@ -88,43 +86,34 @@ namespace eosiobios { * therefore, this method will execute an inline buyram from receiver for newacnt in * an amount equal to the current new account creation fee. */ - [[eosio::action]] - void newaccount( name creator, - name name, - ignore owner, - ignore active){} + [[eosio::action]] void newaccount( name creator, + name name, + ignore owner, + ignore active){} /** - * Update authorization action. - * - * @details Updates pemission for an account. + * \details Updates permission for an account. * - * @param account - the account for which the permission is updated, - * @param pemission - the permission name which is updated, - * @param parem - the parent of the permission which is updated, - * @param aut - the json describing the permission authorization. + * \param account The account for which the permission is updated, + * \param permission The permission name which is updated, + * \param parent The parent of the permission which is updated, + * \param auth The json describing the permission authorization. */ - [[eosio::action]] - void updateauth( ignore account, - ignore permission, - ignore parent, - ignore auth ) {} + [[eosio::action]] void updateauth( ignore account, + ignore permission, + ignore parent, + ignore auth ) {} /** - * Delete authorization action. - * - * @details Deletes the authorization for an account's permision. + * \details Deletes the authorization for an account's permission. * - * @param account - the account for which the permission authorization is deleted, - * @param permission - the permission name been deleted. + * \param account The account for which the permission authorization is deleted, + * \param permission The permission name been deleted. */ - [[eosio::action]] - void deleteauth( ignore account, - ignore permission ) {} + [[eosio::action]] void deleteauth( ignore account, + ignore permission ) {} /** - * Link authorization action. - * - * @details Assigns a specific action from a contract to a permission you have created. Five system + * \details Assigns a specific action from a contract to a permission you have created. Five system * actions can not be linked `updateauth`, `deleteauth`, `linkauth`, `unlinkauth`, and `canceldelay`. * This is useful because when doing authorization checks, the EOSIO based blockchain starts with the * action needed to be authorized (and the contract belonging to), and looks up which permission @@ -133,159 +122,120 @@ namespace eosiobios { * `eosio.any` is an implicit permission which exists on every account; you can link actions to `eosio.any` * and that will make it so linked actions are accessible to any permissions defined for the account. * - * @param account - the permission's owner to be linked and the payer of the RAM needed to store this link, - * @param code - the owner of the action to be linked, - * @param type - the action to be linked, - * @param requirement - the permission to be linked. + * \param account The permission's owner to be linked and the payer of the RAM needed to store this link, + * \param code The owner of the action to be linked, + * \param type The action to be linked, + * \param requirement The permission to be linked. */ - [[eosio::action]] - void linkauth( ignore account, - ignore code, - ignore type, - ignore requirement ) {} + [[eosio::action]] void linkauth( ignore account, + ignore code, + ignore type, + ignore requirement ) {} /** - * Unlink authorization action. - * - * @details It's doing the reverse of linkauth action, by unlinking the given action. + * \details It's doing the reverse of linkauth action, by unlinking the given action. * - * @param account - the owner of the permission to be unlinked and the receiver of the freed RAM, - * @param code - the owner of the action to be unlinked, - * @param type - the action to be unlinked. + * \param account The owner of the permission to be unlinked and the receiver of the freed RAM, + * \param code The owner of the action to be unlinked, + * \param type The action to be unlinked. */ - [[eosio::action]] - void unlinkauth( ignore account, - ignore code, - ignore type ) {} + [[eosio::action]] void unlinkauth( ignore account, + ignore code, + ignore type ) {} /** - * Cancel delay action. + * \details Cancels a deferred transaction. * - * @details Cancels a deferred transaction. - * - * @param canceling_auth - the permission that authorizes this action, - * @param trx_id - the deferred transaction id to be cancelled. + * \param canceling_auth The permission that authorizes this action, + * \param trx_id The deferred transaction id to be cancelled. */ - [[eosio::action]] - void canceldelay( ignore canceling_auth, ignore trx_id ) {} + [[eosio::action]] void canceldelay( ignore canceling_auth, ignore trx_id ) {} /** - * Set code action. - * - * @details Sets the contract code for an account. + * \details Sets the contract code for an account. * - * @param account - the account for which to set the contract code. - * @param vmtype - reserved, set it to zero. - * @param vmversion - reserved, set it to zero. - * @param code - the code content to be set, in the form of a blob binary.. + * \param account The account for which to set the contract code. + * \param vmtype Reserved, set it to zero. + * \param vmversion Reserved, set it to zero. + * \param code The code content to be set, in the form of a blob binary.. */ - [[eosio::action]] - void setcode( name account, uint8_t vmtype, uint8_t vmversion, const std::vector& code ) {} - - /** @}*/ + [[eosio::action]] void setcode( name account, uint8_t vmtype, uint8_t vmversion, const std::vector& code ) {} /** - * Set abi for contract. - * - * @details Set the abi for contract identified by `account` name. Creates an entry in the abi_hash_table + * \details Set the abi for contract identified by `account` name. Creates an entry in the abi_hash_table * index, with `account` name as key, if it is not already present and sets its value with the abi hash. * Otherwise it is updating the current abi hash value for the existing `account` key. * - * @param account - the name of the account to set the abi for - * @param abi - the abi hash represented as a vector of characters + * \param account The name of the account to set the abi for + * \param abi The abi hash represented as a vector of characters */ - [[eosio::action]] - void setabi( name account, const std::vector& abi ); + [[eosio::action]] void setabi( name account, const std::vector& abi ); /** - * On error action. - * - * @details Notification of this action is delivered to the sender of a deferred transaction + * \details Notification of this action is delivered to the sender of a deferred transaction * when an objective error occurs while executing the deferred transaction. * This action is not meant to be called directly. * - * @param sender_id - the id for the deferred transaction chosen by the sender, - * @param sent_trx - the deferred transaction that failed. + * \param sender_id The id for the deferred transaction chosen by the sender, + * \param sent_trx The deferred transaction that failed. */ - [[eosio::action]] - void onerror( ignore sender_id, ignore> sent_trx ); + [[eosio::action]] void onerror( ignore sender_id, ignore> sent_trx ); /** - * Set privilege status for an account. - * - * @details Allows to set privilege status for an account (turn it on/off). - * @param account - the account to set the privileged status for. - * @param is_priv - 0 for false, > 0 for true. + * \details Allows to set privilege status for an account (turn it on/off). + * \param account The account to set the privileged status for. + * \param is_priv 0 for false, > 0 for true. */ - [[eosio::action]] - void setpriv( name account, uint8_t is_priv ); + [[eosio::action]] void setpriv( name account, uint8_t is_priv ); /** - * Set the resource limits of an account + * \details Set the resource limits of an account * - * @details Set the resource limits of an account - * - * @param account - name of the account whose resource limit to be set - * @param ram_bytes - ram limit in absolute bytes - * @param net_weight - fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts) - * @param cpu_weight - fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts) + * \param account The name of the account whose resource limit to be set + * \param ram_bytes The ram limit in absolute bytes + * \param net_weight The fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts) + * \param cpu_weight The fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts) */ - [[eosio::action]] - void setalimits( name account, int64_t ram_bytes, int64_t net_weight, int64_t cpu_weight ); + [[eosio::action]] void setalimits( name account, int64_t ram_bytes, int64_t net_weight, int64_t cpu_weight ); /** - * Set a new list of active producers, that is, a new producers' schedule. - * - * @details Set a new list of active producers, by proposing a schedule change, once the block that + * \details Set a new list of active producers, by proposing a schedule change, once the block that * contains the proposal becomes irreversible, the schedule is promoted to "pending" * automatically. Once the block that promotes the schedule is irreversible, the schedule will * become "active". * - * @param schedule - New list of active producers to set + * \param schedule The new list of active producers to set */ - [[eosio::action]] - void setprods( const std::vector& schedule ); + [[eosio::action]] void setprods( const std::vector& schedule ); /** - * Set the blockchain parameters + * \details Set the blockchain parameters. By tuning these parameters, various degrees of customization can be achieved. * - * @details Set the blockchain parameters. By tuning these parameters, various degrees of customization can be achieved. - * - * @param params - New blockchain parameters to set + * \param params The new blockchain parameters to set */ - [[eosio::action]] - void setparams( const eosio::blockchain_parameters& params ); + [[eosio::action]] void setparams( const eosio::blockchain_parameters& params ); /** - * Check if an account has authorization to access current action. - * - * @details Checks if the account name `from` passed in as param has authorization to access + * \details Checks if the account name `from` passed in as param has authorization to access * current action, that is, if it is listed in the action’s allowed permissions vector. * - * @param from - the account name to authorize + * \param from The account name to authorize */ - [[eosio::action]] - void reqauth( name from ); + [[eosio::action]] void reqauth( name from ); /** - * Activates a protocol feature. + * \details Activates a protocol feature * - * @details Activates a protocol feature - * - * @param feature_digest - hash of the protocol feature to activate. + * \param feature_digest The hash of the protocol feature to activate. */ - [[eosio::action]] - void activate( const eosio::checksum256& feature_digest ); + [[eosio::action]]void activate( const eosio::checksum256& feature_digest ); /** - * Asserts that a protocol feature has been activated. - * - * @details Asserts that a protocol feature has been activated + * \details Asserts that a protocol feature has been activated * - * @param feature_digest - hash of the protocol feature to check for activation. + * \param feature_digest The hash of the protocol feature to check for activation. */ - [[eosio::action]] - void reqactivated( const eosio::checksum256& feature_digest ); + [[eosio::action]] void reqactivated( const eosio::checksum256& feature_digest ); struct [[eosio::table]] abi_hash { name owner; diff --git a/contracts/eosio.msig/include/eosio.msig/eosio.msig.hpp b/contracts/eosio.msig/include/eosio.msig/eosio.msig.hpp index 5278816ac..6423dadde 100644 --- a/contracts/eosio.msig/include/eosio.msig/eosio.msig.hpp +++ b/contracts/eosio.msig/include/eosio.msig/eosio.msig.hpp @@ -8,12 +8,12 @@ namespace eosio { /** - * The `eosio.msig` system contract allows for creation of proposed transactions which require authorization from a list of accounts, approval of the proposed transactions by those accounts required to approve it, and finally, it also allows the execution of the approved transactions on the blockchain. + * \details The `eosio.msig` system contract allows for creation of proposed transactions which require authorization from a list of accounts, approval of the proposed transactions by those accounts required to approve it, and finally, it also allows the execution of the approved transactions on the blockchain. * * In short, the workflow to propose, review, approve and then executed a transaction it can be described by the following: * - first you create a transaction json file, * - then you submit this proposal to the `eosio.msig` contract, and you also insert the account permissions required to approve this proposal into the command that submits the proposal to the blockchain, - * - the proposal then gets stored on the blockchain by the `eosio.msig` contract, and is accessible for review and approval to those accounts required to approve it, + * The proposal then gets stored on the blockchain by the `eosio.msig` contract, and is accessible for review and approval to those accounts required to approve it, * - after each of the appointed accounts required to approve the proposed transactions reviews and approves it, you can execute the proposed transaction. The `eosio.msig` contract will execute it automatically, but not before validating that the transaction has not expired, it is not cancelled, and it has been signed by all the permissions in the initial proposal's required permission list. */ class [[eosio::contract("eosio.msig")]] multisig : public contract { @@ -21,9 +21,7 @@ namespace eosio { using contract::contract; /** - * Create proposal - * - * @details Creates a proposal containing one transaction. + * \details Creates a proposal containing one transaction. * Allows an account `proposer` to make a proposal `proposal_name` which has `requested` * permission levels expected to approve the proposal, and if approved by all expected * permission levels then `trx` transaction can we executed by this proposal. @@ -33,92 +31,76 @@ namespace eosio { * saved in the proposals table and the `requested` permission levels to the * approvals table (for the `proposer` context). Storage changes are billed to `proposer`. * - * @param proposer - The account proposing a transaction - * @param proposal_name - The name of the proposal (should be unique for proposer) - * @param requested - Permission levels expected to approve the proposal - * @param trx - Proposed transaction + * \param proposer The account proposing a transaction. + * \param proposal_name The name of the proposal (should be unique for proposer). + * \param requested The permission levels expected to approve the proposal. + * \param trx The proposed transaction. */ - [[eosio::action]] - void propose(ignore proposer, ignore proposal_name, + [[eosio::action]] void propose(ignore proposer, ignore proposal_name, ignore> requested, ignore trx); /** - * Approve proposal - * - * @details Approves an existing proposal + * \details Approves an existing proposal * Allows an account, the owner of `level` permission, to approve a proposal `proposal_name` * proposed by `proposer`. If the proposal's requested approval list contains the `level` * permission then the `level` permission is moved from internal `requested_approvals` list to * internal `provided_approvals` list of the proposal, thus persisting the approval for * the `proposal_name` proposal. Storage changes are billed to `proposer`. * - * @param proposer - The account proposing a transaction - * @param proposal_name - The name of the proposal (should be unique for proposer) - * @param level - Permission level approving the transaction - * @param proposal_hash - Transaction's checksum + * \param proposer The account proposing a transaction. + * \param proposal_name The name of the proposal (should be unique for proposer). + * \param level The permission level approving the transaction. + * \param proposal_hash The transaction's checksum. */ - [[eosio::action]] - void approve( name proposer, name proposal_name, permission_level level, + [[eosio::action]] void approve( name proposer, name proposal_name, permission_level level, const eosio::binary_extension& proposal_hash ); /** - * Revoke proposal - * - * @details Revokes an existing proposal + * \details Revokes an existing proposal * This action is the reverse of the `approve` action: if all validations pass * the `level` permission is erased from internal `provided_approvals` and added to the internal * `requested_approvals` list, and thus un-approve or revoke the proposal. * - * @param proposer - The account proposing a transaction - * @param proposal_name - The name of the proposal (should be an existing proposal) - * @param level - Permission level revoking approval for proposal + * \param proposer The account proposing a transaction. + * \param proposal_name The name of the proposal (should be an existing proposal). + * \param level The permission level revoking approval for proposal. */ - [[eosio::action]] - void unapprove( name proposer, name proposal_name, permission_level level ); + [[eosio::action]] void unapprove( name proposer, name proposal_name, permission_level level ); /** - * Cancel proposal + * \details Cancels an existing proposal. * - * @details Cancels an existing proposal - * - * @param proposer - The account proposing a transaction - * @param proposal_name - The name of the proposal (should be an existing proposal) - * @param canceler - The account cancelling the proposal (only the proposer can cancel an unexpired transaction, and the canceler has to be different than the proposer) + * \param proposer The account proposing a transaction. + * \param proposal_name The name of the proposal (should be an existing proposal). + * \param canceler The account cancelling the proposal (only the proposer can cancel an unexpired transaction, and the canceler has to be different than the proposer). * * Allows the `canceler` account to cancel the `proposal_name` proposal, created by a `proposer`, * only after time has expired on the proposed transaction. It removes corresponding entries from * internal proptable and from approval (or old approvals) tables as well. */ - [[eosio::action]] - void cancel( name proposer, name proposal_name, name canceler ); + [[eosio::action]] void cancel( name proposer, name proposal_name, name canceler ); /** - * Execute proposal - * - * @details Allows an `executer` account to execute a proposal. + * \details Allows an `executer` account to execute a proposal. * - * Preconditions: - * - `executer` has authorization, - * - `proposal_name` is found in the proposals table, - * - all requested approvals are received, - * - proposed transaction is not expired, - * - and approval accounts are not found in invalidations table. + * \preconditions + * `executer` has authorization, + * `proposal_name` is found in the proposals table, + * all requested approvals are received, + * proposed transaction is not expired, + * and approval accounts are not found in invalidations table. * * If all preconditions are met the transaction is executed as a deferred transaction, * and the proposal is erased from the proposals table. * - * @param proposer - The account proposing a transaction - * @param proposal_name - The name of the proposal (should be an existing proposal) - * @param executer - The account executing the transaction + * \param proposer The account proposing a transaction. + * \param proposal_name The name of the proposal (should be an existing proposal). + * \param executer The account executing the transaction. */ - [[eosio::action]] - void exec( name proposer, name proposal_name, name executer ); + [[eosio::action]] void exec( name proposer, name proposal_name, name executer ); /** - * Invalidate proposal - * - * @details Allows an `account` to invalidate itself, that is, its name is added to + * \details Allows an `account` to invalidate itself, that is, its name is added to * the invalidations table and this table will be cross referenced when exec is performed. * - * @param account - The account invalidating the transaction + * \param account The account invalidating the transaction. */ - [[eosio::action]] - void invalidate( name account ); + [[eosio::action]] void invalidate( name account ); using propose_action = eosio::action_wrapper<"propose"_n, &multisig::propose>; using approve_action = eosio::action_wrapper<"approve"_n, &multisig::approve>; @@ -173,4 +155,4 @@ namespace eosio { typedef eosio::multi_index< "invals"_n, invalidation > invalidations; }; -} /// namespace eosio +} diff --git a/contracts/eosio.msig/src/eosio.msig.cpp b/contracts/eosio.msig/src/eosio.msig.cpp index 176921929..34ae190cd 100644 --- a/contracts/eosio.msig/src/eosio.msig.cpp +++ b/contracts/eosio.msig/src/eosio.msig.cpp @@ -204,4 +204,4 @@ void multisig::invalidate( name account ) { } } -} /// namespace eosio +} diff --git a/contracts/eosio.system/include/eosio.system/eosio.system.hpp b/contracts/eosio.system/include/eosio.system/eosio.system.hpp index 8567bcf8b..acf799113 100644 --- a/contracts/eosio.system/include/eosio.system/eosio.system.hpp +++ b/contracts/eosio.system/include/eosio.system/eosio.system.hpp @@ -79,10 +79,10 @@ namespace eosiosystem { static constexpr int64_t default_votepay_factor = 40000; // per-block pay share = 10000 / 40000 = 25% of the producer pay // A name bid, which consists of: - // - a `newname` name that the bid is for - // - a `high_bidder` account name that is the one with the highest bid so far - // - the `high_bid` which is amount of highest bid - // - and `last_bid_time` which is the time of the highest bid + // - a `newname` name that the bid is for, + // - a `high_bidder` account name that is the one with the highest bid so far, + // - the `high_bid` which is amount of highest bid, + // - and `last_bid_time` which is the time of the highest bid. struct [[eosio::table, eosio::contract("eosio.system")]] name_bid { name newname; name high_bidder; @@ -94,8 +94,8 @@ namespace eosiosystem { }; // A bid refund, which is defined by: - // - the `bidder` account name owning the refund - // - the `amount` to be refunded + // - the `bidder` account name owning the refund, + // - the `amount` to be refunded. struct [[eosio::table, eosio::contract("eosio.system")]] bid_refund { name bidder; asset amount; @@ -393,7 +393,7 @@ namespace eosiosystem { asset vote_stake; asset rex_balance; int64_t matured_rex = 0; - std::deque> rex_maturities; /// REX daily maturity buckets + std::deque> rex_maturities; // REX daily maturity buckets uint64_t primary_key()const { return owner.value; } }; @@ -512,8 +512,8 @@ namespace eosiosystem { system_contract( name s, name code, datastream ds ); ~system_contract(); - // Returns the core symbol by system account name - // @param system_account - the system account to get the core symbol for. + /// \details Returns the core symbol by system account name + /// \param system_account The system account to get the core symbol for. static symbol get_core_symbol( name system_account = "eosio"_n ) { rammarket rm(system_account, system_account.value); const static auto sym = get_core_symbol( rm ); @@ -522,195 +522,185 @@ namespace eosiosystem { // Actions: /** - * The Init action initializes the system contract for a version and a symbol. + * \details The Init action initializes the system contract for a version and a symbol. * Only succeeds when: * - version is 0 and * - symbol is found and - * - system token supply is greater than 0, - * - and system contract wasn’t already been initialized. + * - system token supply is greater than 0 and + * - system contract wasn’t already been initialized. * - * @param version - the version, has to be 0, - * @param core - the system symbol. + * \param version The version, has to be 0. + * \param core The system symbol. */ - [[eosio::action]] - void init( unsigned_int version, const symbol& core ); + [[eosio::action]] void init( unsigned_int version, const symbol& core ); /** - * On block action. This special action is triggered when a block is applied by the given producer + * \details On block action. This special action is triggered when a block is applied by the given producer * and cannot be generated from any other source. It is used to pay producers and calculate * missed blocks of other producers. Producer pay is deposited into the producer's stake * balance and can be withdrawn over time. If blocknum is the start of a new round this may * update the active producer config from the producer votes. * - * @param header - the block header produced. + * \param header The block header produced. */ - [[eosio::action]] - void onblock( ignore header ); + [[eosio::action]] void onblock( ignore header ); /** - * Set account limits action sets the resource limits of an account + * \details Set account limits action sets the resource limits of an account * - * @param account - name of the account whose resource limit to be set, - * @param ram_bytes - ram limit in absolute bytes, - * @param net_weight - fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts), - * @param cpu_weight - fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts). + * \param account The name of the account whose resource limit to be set. + * \param ram_bytes The ram limit in absolute bytes. + * \param net_weight The fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts). + * \param cpu_weight The fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts). */ - [[eosio::action]] - void setalimits( const name& account, int64_t ram_bytes, int64_t net_weight, int64_t cpu_weight ); + [[eosio::action]] void setalimits( const name& account, + int64_t ram_bytes, + int64_t net_weight, + int64_t cpu_weight ); /** - * Set account RAM limits action, which sets the RAM limits of an account + * \details Set account RAM limits action, which sets the RAM limits of an account * - * @param account - name of the account whose resource limit to be set, - * @param ram_bytes - ram limit in absolute bytes. + * \param account The name of the account whose resource limit to be set. + * \param ram_bytes The ram limit in absolute bytes. */ - [[eosio::action]] - void setacctram( const name& account, const std::optional& ram_bytes ); + [[eosio::action]] void setacctram( const name& account, + const std::optional& ram_bytes ); /** - * Set account NET limits action, which sets the NET limits of an account + * \details Set account NET limits action, which sets the NET limits of an account * - * @param account - name of the account whose resource limit to be set, - * @param net_weight - fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts). + * \param account The name of the account whose resource limit to be set. + * \param net_weight The fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts). */ - [[eosio::action]] - void setacctnet( const name& account, const std::optional& net_weight ); + [[eosio::action]] void setacctnet( const name& account, + const std::optional& net_weight ); /** - * Set account CPU limits action, which sets the CPU limits of an account + * \details Set account CPU limits action, which sets the CPU limits of an account * - * @param account - name of the account whose resource limit to be set, - * @param cpu_weight - fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts). + * \param account The name of the account whose resource limit to be set. + * \param cpu_weight The fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts). */ - [[eosio::action]] - void setacctcpu( const name& account, const std::optional& cpu_weight ); - + [[eosio::action]] void setacctcpu( const name& account, + const std::optional& cpu_weight ); /** - * Activates a protocol feature + * \details Activates a protocol feature * - * @param feature_digest - hash of the protocol feature to activate. + * \param feature_digest The hash of the protocol feature to activate. */ - [[eosio::action]] - void activate( const eosio::checksum256& feature_digest ); + [[eosio::action]] void activate( const eosio::checksum256& feature_digest ); // functions defined in delegate_bandwidth.cpp /** - * Delegate bandwidth and/or cpu action. Stakes SYS from the balance of `from` for the benefit of `receiver`. + * \details Delegate bandwidth and/or cpu action. Stakes SYS from the balance of `from` for the benefit of `receiver`. * - * @param from - the account to delegate bandwidth from, that is, the account holding - * tokens to be staked, - * @param receiver - the account to delegate bandwith to, that is, the account to - * whose resources staked tokens are added - * @param stake_net_quantity - tokens staked for NET bandwidth, - * @param stake_cpu_quantity - tokens staked for CPU bandwidth, - * @param transfer - if true, ownership of staked tokens is transfered to `receiver`. + * \param from The account to delegate bandwidth from, that is, the account holding tokens to be staked. + * \param receiver The account to delegate bandwith to, that is, the account to whose resources staked tokens are added. + * \param stake_net_quantity The tokens staked for NET bandwidth. + * \param stake_cpu_quantity The tokens staked for CPU bandwidth + * \param transfer If true, ownership of staked tokens is transferred to `receiver`. * - * @post All producers `from` account has voted for will have their votes updated immediately. + * \postconditions All producers `from` account has voted for will have their votes updated immediately. */ - [[eosio::action]] - void delegatebw( const name& from, const name& receiver, - const asset& stake_net_quantity, const asset& stake_cpu_quantity, bool transfer ); + [[eosio::action]] void delegatebw( const name& from, + const name& receiver, + const asset& stake_net_quantity, + const asset& stake_cpu_quantity, + bool transfer ); /** - * Setrex action. - * - * @details Sets total_rent balance of REX pool to the passed value. - * @param balance - amount to set the REX pool balance. + * \details Sets total_rent balance of REX pool to the passed value. + * \param balance The amount to set the REX pool balance. */ - [[eosio::action]] - void setrex( const asset& balance ); + [[eosio::action]] void setrex( const asset& balance ); /** - * Deposit to REX fund action. Deposits core tokens to user REX fund. + * \details Deposit to REX fund action. Deposits core tokens to user REX fund. * All proceeds and expenses related to REX are added to or taken out of this fund. * An inline transfer from 'owner' liquid balance is executed. * All REX-related costs and proceeds are deducted from and added to 'owner' REX fund, * with one exception being buying REX using staked tokens. * Storage change is billed to 'owner'. * - * @param owner - REX fund owner account, - * @param amount - amount of tokens to be deposited. + * \param owner The REX fund owner account. + * \param amount The amount of tokens to be deposited. */ - [[eosio::action]] - void deposit( const name& owner, const asset& amount ); + [[eosio::action]] void deposit( const name& owner, const asset& amount ); /** - * Withdraw from REX fund action. - * - * @details Withdraws core tokens from user REX fund. + * \details Withdraws core tokens from user REX fund. * An inline token transfer to user balance is executed. * - * @param owner - REX fund owner account, - * @param amount - amount of tokens to be withdrawn. + * \param owner The REX fund owner account. + * \param amount The amount of tokens to be withdrawn. */ - [[eosio::action]] - void withdraw( const name& owner, const asset& amount ); + [[eosio::action]] void withdraw( const name& owner, const asset& amount ); /** - * Buyrex action. Buys REX in exchange for tokens taken out of user's REX fund by transfering + * \details Buyrex action. Buys REX in exchange for tokens taken out of user's REX fund by transfering * core tokens from user REX fund and converts them to REX stake. By buying REX, user is * lending tokens in order to be rented as CPU or NET resourses. * Storage change is billed to 'from' account. * - * @param from - owner account name, - * @param amount - amount of tokens taken out of 'from' REX fund. + * \param from The owner account name. + * \param amount Tne amount of tokens taken out of 'from' REX fund. * - * @pre A voting requirement must be satisfied before action can be executed. - * @pre User must vote for at least 21 producers or delegate vote to proxy before buying REX. + * \preconditions A voting requirement must be satisfied before action can be executed and + * user must vote for at least 21 producers or delegate vote to proxy before buying REX. * - * @post User votes are updated following this action. - * @post Tokens used in purchase are added to user's voting power. - * @post Bought REX cannot be sold before 4 days counting from end of day of purchase. + * \postconditions User votes are updated following this action, + * tokens used in purchase are added to user's voting power and + * bought REX cannot be sold before 4 days counting from end of day of purchase. */ - [[eosio::action]] - void buyrex( const name& from, const asset& amount ); + [[eosio::action]] void buyrex( const name& from, const asset& amount ); /** - * Unstaketorex action. Use staked core tokens to buy REX. + * \details Unstaketorex action. Use staked core tokens to buy REX. * Storage change is billed to 'owner' account. * - * @param owner - owner of staked tokens, - * @param receiver - account name that tokens have previously been staked to, - * @param from_net - amount of tokens to be unstaked from NET bandwidth and used for REX purchase, - * @param from_cpu - amount of tokens to be unstaked from CPU bandwidth and used for REX purchase. + * \param owner The owner of staked tokens. + * \param receiver The account name that tokens have previously been staked to. + * \param from_net The amount of tokens to be unstaked from NET bandwidth and used for REX purchase. + * \param from_cpu The amount of tokens to be unstaked from CPU bandwidth and used for REX purchase. * - * @pre A voting requirement must be satisfied before action can be executed. - * @pre User must vote for at least 21 producers or delegate vote to proxy before buying REX. + * \preconditions A voting requirement must be satisfied before action can be executed and + * user must vote for at least 21 producers or delegate vote to proxy before buying REX. * - * @post User votes are updated following this action. - * @post Tokens used in purchase are added to user's voting power. - * @post Bought REX cannot be sold before 4 days counting from end of day of purchase. + * \postconditions User votes are updated following this action, + * tokens used in purchase are added to user's voting power and + * bought REX cannot be sold before 4 days counting from end of day of purchase. */ - [[eosio::action]] - void unstaketorex( const name& owner, const name& receiver, const asset& from_net, const asset& from_cpu ); + [[eosio::action]] void unstaketorex( const name& owner, + const name& receiver, + const asset& from_net, + const asset& from_cpu ); /** - * Sellrex action. Sells REX in exchange for core tokens by converting REX stake back into core tokens + * \details Sellrex action. Sells REX in exchange for core tokens by converting REX stake back into core tokens * at current exchange rate. If order cannot be processed, it gets queued until there is enough * in REX pool to fill order, and will be processed within 30 days at most. If successful, user * votes are updated, that is, proceeds are deducted from user's voting power. In case sell order * is queued, storage change is billed to 'from' account. * - * @param from - owner account of REX, - * @param rex - amount of REX to be sold. + * \param from The owner account of REX. + * \param rex The amount of REX to be sold. */ - [[eosio::action]] - void sellrex( const name& from, const asset& rex ); + [[eosio::action]] void sellrex( const name& from, const asset& rex ); /** - * Cnclrexorder action. Cancels unfilled REX sell order by owner if one exists. + * \details Cnclrexorder action. Cancels unfilled REX sell order by owner if one exists. * - * @param owner - owner account name. + * \param owner The owner account name. * - * @pre Order cannot be cancelled once it's been filled. + * \preconditions Order cannot be cancelled once it's been filled. */ - [[eosio::action]] - void cnclrexorder( const name& owner ); + [[eosio::action]] void cnclrexorder( const name& owner ); /** - * Rentcpu action. Use payment to rent as many SYS tokens as possible as determined by market price and + * \details Rentcpu action. Use payment to rent as many SYS tokens as possible as determined by market price and * stake them for CPU for the benefit of receiver, after 30 days the rented core delegation of CPU * will expire. At expiration, if balance is greater than or equal to `loan_payment`, `loan_payment` * is taken out of loan balance and used to renew the loan. Otherwise, the loan is closed and user @@ -718,19 +708,21 @@ namespace eosiosystem { * Owner can fund or refund a loan at any time before its expiration. * All loan expenses and refunds come out of or are added to owner's REX fund. * - * @param from - account creating and paying for CPU loan, 'from' account can add tokens to loan - * balance using action `fundcpuloan` and withdraw from loan balance using `defcpuloan` - * @param receiver - account receiving rented CPU resources, - * @param loan_payment - tokens paid for the loan, it has to be greater than zero, - * amount of rented resources is calculated from `loan_payment`, - * @param loan_fund - additional tokens can be zero, and is added to loan balance. + * \param from The account creating and paying for CPU loan, 'from' account can add tokens to loan + * balance using action `fundcpuloan` and withdraw from loan balance using `defcpuloan`. + * \param receiver The account receiving rented CPU resources. + * \param loan_payment The tokens paid for the loan, it has to be greater than zero, + * amount of rented resources is calculated from `loan_payment`. + * \param loan_fund - additional tokens can be zero, and is added to loan balance. * Loan balance represents a reserve that is used at expiration for automatic loan renewal. */ - [[eosio::action]] - void rentcpu( const name& from, const name& receiver, const asset& loan_payment, const asset& loan_fund ); + [[eosio::action]] void rentcpu( const name& from, + const name& receiver, + const asset& loan_payment, + const asset& loan_fund ); /** - * Rentnet action. Use payment to rent as many SYS tokens as possible as determined by market price and + * \details Rentnet action. Use payment to rent as many SYS tokens as possible as determined by market price and * stake them for NET for the benefit of receiver, after 30 days the rented core delegation of NET * will expire. At expiration, if balance is greater than or equal to `loan_payment`, `loan_payment` * is taken out of loan balance and used to renew the loan. Otherwise, the loan is closed and user @@ -738,124 +730,124 @@ namespace eosiosystem { * Owner can fund or refund a loan at any time before its expiration. * All loan expenses and refunds come out of or are added to owner's REX fund. * - * @param from - account creating and paying for NET loan, 'from' account can add tokens to loan - * balance using action `fundnetloan` and withdraw from loan balance using `defnetloan`, - * @param receiver - account receiving rented NET resources, - * @param loan_payment - tokens paid for the loan, it has to be greater than zero, - * amount of rented resources is calculated from `loan_payment`, - * @param loan_fund - additional tokens can be zero, and is added to loan balance. + * \param from The account creating and paying for NET loan, 'from' account can add tokens to loan + * balance using action `fundnetloan` and withdraw from loan balance using `defnetloan`. + * \param receiver The account receiving rented NET resources. + * \param loan_payment The tokens paid for the loan, it has to be greater than zero, + * amount of rented resources is calculated from `loan_payment`. + * \param loan_fund - additional tokens can be zero, and is added to loan balance. * Loan balance represents a reserve that is used at expiration for automatic loan renewal. */ - [[eosio::action]] - void rentnet( const name& from, const name& receiver, const asset& loan_payment, const asset& loan_fund ); + [[eosio::action]] void rentnet( const name& from, + const name& receiver, + const asset& loan_payment, + const asset& loan_fund ); /** - * Fundcpuloan action. Transfers tokens from REX fund to the fund of a specific CPU loan in order to + * \details Fundcpuloan action. Transfers tokens from REX fund to the fund of a specific CPU loan in order to * be used for loan renewal at expiry. * - * @param from - loan creator account, - * @param loan_num - loan id, - * @param payment - tokens transfered from REX fund to loan fund. + * \param from The loan creator account. + * \param loan_num The loan id. + * \param payment The tokens transfered from REX fund to loan fund. */ - [[eosio::action]] - void fundcpuloan( const name& from, uint64_t loan_num, const asset& payment ); + [[eosio::action]] void fundcpuloan( const name& from, + uint64_t loan_num, + const asset& payment ); /** - * Fundnetloan action. Transfers tokens from REX fund to the fund of a specific NET loan in order to + * \details Fundnetloan action. Transfers tokens from REX fund to the fund of a specific NET loan in order to * be used for loan renewal at expiry. * - * @param from - loan creator account, - * @param loan_num - loan id, - * @param payment - tokens transfered from REX fund to loan fund. + * \param from The loan creator account. + * \param loan_num The loan id. + * \param payment The tokens transfered from REX fund to loan fund. */ - [[eosio::action]] - void fundnetloan( const name& from, uint64_t loan_num, const asset& payment ); + [[eosio::action]] void fundnetloan( const name& from, + uint64_t loan_num, + const asset& payment ); /** - * Defcpuloan action. Withdraws tokens from the fund of a specific CPU loan and adds them to REX fund. + * \details Defcpuloan action. Withdraws tokens from the fund of a specific CPU loan and adds them to REX fund. * - * @param from - loan creator account, - * @param loan_num - loan id, - * @param amount - tokens transfered from CPU loan fund to REX fund. + * \param from The loan creator account. + * \param loan_num The loan id. + * \param amount The tokens transfered from CPU loan fund to REX fund. */ - [[eosio::action]] - void defcpuloan( const name& from, uint64_t loan_num, const asset& amount ); + [[eosio::action]] void defcpuloan( const name& from, + uint64_t loan_num, + const asset& amount ); /** - * Defnetloan action. Withdraws tokens from the fund of a specific NET loan and adds them to REX fund. + * \details Defnetloan action. Withdraws tokens from the fund of a specific NET loan and adds them to REX fund. * - * @param from - loan creator account, - * @param loan_num - loan id, - * @param amount - tokens transfered from NET loan fund to REX fund. + * \param from The loan creator account. + * \param loan_num The loan id. + * \param amount The tokens transfered from NET loan fund to REX fund. */ - [[eosio::action]] - void defnetloan( const name& from, uint64_t loan_num, const asset& amount ); + [[eosio::action]] void defnetloan( const name& from, + uint64_t loan_num, + const asset& amount ); /** - * Updaterex action. Updates REX owner vote weight to current value of held REX tokens. + * \details Updaterex action. Updates REX owner vote weight to current value of held REX tokens. * - * @param owner - REX owner account. + * \param owner The REX owner account. */ - [[eosio::action]] - void updaterex( const name& owner ); + [[eosio::action]] void updaterex( const name& owner ); /** - * Rexexec action. Processes max CPU loans, max NET loans, and max queued sellrex orders. + * \details Rexexec action. Processes max CPU loans, max NET loans, and max queued sellrex orders. * Action does not execute anything related to a specific user. * - * @param user - any account can execute this action, - * @param max - number of each of CPU loans, NET loans, and sell orders to be processed. + * \param user The account that can execute this action, + * \param max The number of each of CPU loans, NET loans, and sell orders to be processed. */ - [[eosio::action]] - void rexexec( const name& user, uint16_t max ); + [[eosio::action]] void rexexec( const name& user, uint16_t max ); /** - * Consolidate action. Consolidates REX maturity buckets into one bucket that can be sold after 4 days + * \details Consolidate action. Consolidates REX maturity buckets into one bucket that can be sold after 4 days * starting from the end of the day. * - * @param owner - REX owner account name. + * \param owner The REX owner account name. */ - [[eosio::action]] - void consolidate( const name& owner ); + [[eosio::action]] void consolidate( const name& owner ); /** - * Mvtosavings action. Moves a specified amount of REX into savings bucket. REX savings bucket + * \details Mvtosavings action. Moves a specified amount of REX into savings bucket. REX savings bucket * never matures. In order for it to be sold, it has to be moved explicitly * out of that bucket. Then the moved amount will have the regular maturity * period of 4 days starting from the end of the day. * - * @param owner - REX owner account name. - * @param rex - amount of REX to be moved. + * \param owner The REX owner account name. + * \param rex The amount of REX to be moved. */ - [[eosio::action]] - void mvtosavings( const name& owner, const asset& rex ); + [[eosio::action]] void mvtosavings( const name& owner, const asset& rex ); /** - * Mvfrsavings action. Moves a specified amount of REX out of savings bucket. The moved amount + * \details Mvfrsavings action. Moves a specified amount of REX out of savings bucket. The moved amount * will have the regular REX maturity period of 4 days. * - * @param owner - REX owner account name. - * @param rex - amount of REX to be moved. + * \param owner The REX owner account name. + * \param rex The amount of REX to be moved. */ - [[eosio::action]] - void mvfrsavings( const name& owner, const asset& rex ); + [[eosio::action]] void mvfrsavings( const name& owner, const asset& rex ); /** - * Closerex action. Deletes owner records from REX tables and frees used RAM. Owner must not have + * \details Closerex action. Deletes owner records from REX tables and frees used RAM. Owner must not have * an outstanding REX balance. * - * @param owner - user account name. + * \param owner The user account name. * - * @pre If owner has a non-zero REX balance, the action fails; otherwise, - * owner REX balance entry is deleted. - * @pre If owner has no outstanding loans and a zero REX fund balance, + * \preconditions If owner has a non-zero REX balance, the action fails; + * otherwise, owner REX balance entry is deleted. + * If owner has no outstanding loans and a zero REX fund balance, * REX fund entry is deleted. */ - [[eosio::action]] - void closerex( const name& owner ); + [[eosio::action]] void closerex( const name& owner ); /** - * Undelegate bandwitdh action. Decreases the total tokens delegated by `from` to `receiver` and/or + * \details Undelegate bandwidth action. Decreases the total tokens delegated by `from` to `receiver` and/or * frees the memory associated with the delegation if there is nothing * left to delegate. * This will cause an immediate reduction in net/cpu bandwidth of the @@ -867,259 +859,252 @@ namespace eosiosystem { * The `from` account loses voting power as a result of this call and * all producer tallies are updated. * - * @param from - the account to undelegate bandwidth from, that is, - * the account whose tokens will be unstaked, - * @param receiver - the account to undelegate bandwith to, that is, - * the account to whose benefit tokens have been staked, - * @param unstake_net_quantity - tokens to be unstaked from NET bandwidth, - * @param unstake_cpu_quantity - tokens to be unstaked from CPU bandwidth, + * \param from The account to undelegate bandwidth from, that is, + * the account whose tokens will be unstaked. + * \param receiver The account to undelegate bandwith to, that is, + * the account to whose benefit tokens have been staked. + * \param unstake_net_quantity The tokens to be unstaked from NET bandwidth. + * \param unstake_cpu_quantity The tokens to be unstaked from CPU bandwidth. * - * @post Unstaked tokens are transferred to `from` liquid balance via a + * \postconditions Unstaked tokens are transferred to `from` liquid balance via a * deferred transaction with a delay of 3 days. - * @post If called during the delay period of a previous `undelegatebw` + * If called during the delay period of a previous `undelegatebw` * action, pending action is canceled and timer is reset. - * @post All producers `from` account has voted for will have their votes updated immediately. - * @post Bandwidth and storage for the deferred transaction are billed to `from`. + * All producers `from` account has voted for will have their votes updated immediately. + * Bandwidth and storage for the deferred transaction are billed to `from`. */ - [[eosio::action]] - void undelegatebw( const name& from, const name& receiver, - const asset& unstake_net_quantity, const asset& unstake_cpu_quantity ); + [[eosio::action]] void undelegatebw( const name& from, + const name& receiver, + const asset& unstake_net_quantity, + const asset& unstake_cpu_quantity ); /** - * Buy ram action. Increases receiver's ram quota based upon current price and quantity of + * \details Buy ram action. Increases receiver's ram quota based upon current price and quantity of * tokens provided. An inline transfer from receiver to system contract of * tokens will be executed. * - * @param payer - the ram buyer, - * @param receiver - the ram receiver, - * @param quant - the quntity of tokens to buy ram with. + * \param payer The ram buyer. + * \param receiver The ram receiver. + * \param quant The quntity of tokens to buy ram with. */ - [[eosio::action]] - void buyram( const name& payer, const name& receiver, const asset& quant ); + [[eosio::action]] void buyram( const name& payer, + const name& receiver, + const asset& quant ); /** - * Buy a specific amount of ram bytes action. Increases receiver's ram in quantity of bytes provided. + * \details Buy a specific amount of ram bytes action. Increases receiver's ram in quantity of bytes provided. * An inline transfer from receiver to system contract of tokens will be executed. * - * @param payer - the ram buyer, - * @param receiver - the ram receiver, - * @param bytes - the quntity of ram to buy specified in bytes. + * \param payer The ram buyer. + * \param receiver The ram receiver. + * \param bytes The quantity of ram to buy specified in bytes. */ - [[eosio::action]] - void buyrambytes( const name& payer, const name& receiver, uint32_t bytes ); + [[eosio::action]] void buyrambytes( const name& payer, + const name& receiver, + uint32_t bytes ); /** - * Sell ram action. Reduces quota by bytes and then performs an inline transfer of tokens + * \details Sell ram action. Reduces quota by bytes and then performs an inline transfer of tokens * to receiver based upon the average purchase price of the original quota. * - * @param account - the ram seller account, - * @param bytes - the amount of ram to sell in bytes. + * \param account The ram seller account. + * \param bytes The amount of ram to sell in bytes. */ - [[eosio::action]] - void sellram( const name& account, int64_t bytes ); + [[eosio::action]] void sellram( const name& account, int64_t bytes ); /** - * Refund action. This action is called after the delegation-period to claim all pending + * \details Refund action. This action is called after the delegation-period to claim all pending * unstaked tokens belonging to owner. * - * @param owner - the owner of the tokens claimed. + * \param owner The owner of the tokens claimed. */ - [[eosio::action]] - void refund( const name& owner ); + [[eosio::action]] void refund( const name& owner ); // functions defined in voting.cpp /** - * Register producer action. Register producer action, indicates that a particular account wishes to become a producer, + * \details Register producer action. Register producer action, indicates that a particular account wishes to become a producer, * this action will create a `producer_config` and a `producer_info` object for `producer` scope * in producers tables. * - * @param producer - account registering to be a producer candidate, - * @param producer_key - the public key of the block producer, this is the key used by block producer to sign blocks, - * @param url - the url of the block producer, normally the url of the block producer presentation website, - * @param location - is the country code as defined in the ISO 3166, https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes + * \param producer The account registering to be a producer candidate. + * \param producer_key The public key of the block producer, this is the key used by block producer to sign blocks. + * \param url The url of the block producer, normally the url of the block producer presentation website. + * \param location The country code as defined in the ISO 3166, https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes * - * @pre Producer to register is an account - * @pre Authority of producer to register + * \preconditions Producer to register is an account. + * Authority of producer to register. */ - [[eosio::action]] - void regproducer( const name& producer, const public_key& producer_key, const std::string& url, uint16_t location ); + [[eosio::action]] void regproducer( const name& producer, + const public_key& producer_key, + const std::string& url, + uint16_t location ); /** - * Register producer action. - * - * @details Register producer action, indicates that a particular account wishes to become a producer, + * \details Register producer action, indicates that a particular account wishes to become a producer, * this action will create a `producer_config` and a `producer_info` object for `producer` scope * in producers tables. * - * @param producer - account registering to be a producer candidate, - * @param producer_authority - the weighted threshold multisig block signing authority of the block producer used to sign blocks, - * @param url - the url of the block producer, normally the url of the block producer presentation website, - * @param location - is the country code as defined in the ISO 3166, https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes + * \param producer The account registering to be a producer candidate. + * \param producer_authority The weighted threshold multisig block signing authority of the block producer used to sign blocks. + * \param url The url of the block producer, normally the url of the block producer presentation website. + * \param location The country code as defined in the ISO 3166, https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes * - * @pre Producer to register is an account - * @pre Authority of producer to register + * \preconditions Producer to register is an account. + * Authority of producer to register. */ - [[eosio::action]] - void regproducer2( const name& producer, const eosio::block_signing_authority& producer_authority, const std::string& url, uint16_t location ); + [[eosio::action]] void regproducer2( const name& producer, + const eosio::block_signing_authority& producer_authority, + const std::string& url, + uint16_t location ); /** - * Unregister producer action. Deactivate the block producer with account name `producer`. - * - * @details Deactivate the block producer with account name `producer`. - * @param producer - the block producer account to unregister. + * \details Deactivate the block producer with account name `producer`. + * \param producer The block producer account to unregister. */ - [[eosio::action]] - void unregprod( const name& producer ); + [[eosio::action]] void unregprod( const name& producer ); /** - * Set ram action sets the ram supply - * @param max_ram_size - the amount of ram supply to set. + * \details Set ram action sets the ram supply. + * \param max_ram_size The amount of ram supply to set. */ - [[eosio::action]] - void setram( uint64_t max_ram_size ); + [[eosio::action]] void setram( uint64_t max_ram_size ); /** - * Set ram rate action. Sets the rate of increase of RAM in bytes per block. It is capped by the uint16_t to + * \details Set ram rate action. Sets the rate of increase of RAM in bytes per block. It is capped by the uint16_t to * a maximum rate of 3 TB per year. If update_ram_supply hasn't been called for the most recent block, * then new ram will be allocated at the old rate up to the present block before switching the rate. * - * @param bytes_per_block - the amount of bytes per block increase to set. + * \param bytes_per_block The amount of bytes per block increase to set. */ - [[eosio::action]] - void setramrate( uint16_t bytes_per_block ); + [[eosio::action]] void setramrate( uint16_t bytes_per_block ); /** - * Vote producer action. Votes for a set of producers. This action updates the list of `producers` voted for, + * \details Vote producer action. Votes for a set of producers. This action updates the list of `producers` voted for, * for `voter` account. If voting for a `proxy`, the producer votes will not change until the * proxy updates their own vote. Voter can vote for a proxy __or__ a list of at most 30 producers. * Storage change is billed to `voter`. * - * @param voter - the account to change the voted producers for, - * @param proxy - the proxy to change the voted producers for, - * @param producers - the list of producers to vote for, a maximum of 30 producers is allowed. + * \param voter The account to change the voted producers for. + * \param proxy The proxy to change the voted producers for. + * \param producers The list of producers to vote for, a maximum of 30 producers is allowed. * - * @pre Producers must be sorted from lowest to highest and must be registered and active - * @pre If proxy is set then no producers can be voted for - * @pre If proxy is set then proxy account must exist and be registered as a proxy - * @pre Every listed producer or proxy must have been previously registered - * @pre Voter must authorize this action - * @pre Voter must have previously staked some EOS for voting - * @pre Voter->staked must be up to date + * \preconditions Producers must be sorted from lowest to highest and must be registered and active. + * If proxy is set then no producers can be voted for. + * If proxy is set then proxy account must exist and be registered as a proxy. + * Every listed producer or proxy must have been previously registered. + * Voter must authorize this action. + * Voter must have previously staked some EOS for voting. + * Voter->staked must be up to date. * - * @post Every producer previously voted for will have vote reduced by previous vote weight - * @post Every producer newly voted for will have vote increased by new vote amount - * @post Prior proxy will proxied_vote_weight decremented by previous vote weight - * @post New proxy will proxied_vote_weight incremented by new vote weight + * \postconditions Every producer previously voted for will have vote reduced by previous vote weight. + * Every producer newly voted for will have vote increased by new vote amount. + * Prior proxy will proxied_vote_weight decremented by previous vote weight. + * New proxy will proxied_vote_weight incremented by new vote weight. */ - [[eosio::action]] - void voteproducer( const name& voter, const name& proxy, const std::vector& producers ); + [[eosio::action]] void voteproducer( const name& voter, + const name& proxy, + const std::vector& producers ); /** - * Register proxy action. Set `proxy` account as proxy. + * \details Register proxy action. Set `proxy` account as proxy. * An account marked as a proxy can vote with the weight of other accounts which * have selected it as a proxy. Other accounts must refresh their voteproducer to * update the proxy's weight. * Storage change is billed to `proxy`. * - * @param rpoxy - the account registering as voter proxy (or unregistering), - * @param isproxy - if true, proxy is registered; if false, proxy is unregistered. + * \param proxy The account registering as voter proxy (or unregistering). + * \param isproxy If true, proxy is registered; if false, proxy is unregistered. * - * @pre Proxy must have something staked (existing row in voters table) - * @pre New state must be different than current state + * \preconditions Proxy must have something staked (existing row in voters table) + * New state must be different than current state */ - [[eosio::action]] - void regproxy( const name& proxy, bool isproxy ); + [[eosio::action]] void regproxy( const name& proxy, bool isproxy ); /** - * Set the blockchain parameters Set the blockchain parameters. By tunning these parameters a degree of + * \details Set the blockchain parameters Set the blockchain parameters. By tunning these parameters a degree of * customization can be achieved. - * @param params - New blockchain parameters to set. + * \param params - New blockchain parameters to set. */ - [[eosio::action]] - void setparams( const eosio::blockchain_parameters& params ); + [[eosio::action]] void setparams( const eosio::blockchain_parameters& params ); /** - * Claim rewards action. Claim block producing and vote rewards. - * @param owner - producer account claiming per-block and per-vote rewards. + * \details Claim rewards action. Claim block producing and vote rewards. + * \param owner - producer account claiming per-block and per-vote rewards. */ - [[eosio::action]] - void claimrewards( const name& owner ); + [[eosio::action]] void claimrewards( const name& owner ); /** - * Set privilege status for an account. Allows to set privilege status for an account (turn it on/off). - * @param account - the account to set the privileged status for. - * @param is_priv - 0 for false, > 0 for true. + * \details Set privilege status for an account. Allows to set privilege status for an account (turn it on/off). + * \param account The account to set the privileged status for. + * \param is_priv - 0 for false, > 0 for true. */ - [[eosio::action]] - void setpriv( const name& account, uint8_t is_priv ); + [[eosio::action]] void setpriv( const name& account, uint8_t is_priv ); /** - * Remove producer action. Deactivates a producer by name, if not found asserts. - * @param producer - the producer account to deactivate. + * \details Remove producer action. Deactivates a producer by name, if not found asserts. + * \param producer The producer account to deactivate. */ - [[eosio::action]] - void rmvproducer( const name& producer ); + [[eosio::action]] void rmvproducer( const name& producer ); /** - * Update revision action. Updates the current revision. - * @param revision - it has to be incremented by 1 compared with current revision. + * \details Update revision action. Updates the current revision. + * \param revision - it has to be incremented by 1 compared with current revision. * - * @pre Current revision can not be higher than 254, and has to be smaller + * \preconditions Current revision can not be higher than 254, and has to be smaller * than or equal 1 (“set upper bound to greatest revision supported in the code”). */ - [[eosio::action]] - void updtrevision( uint8_t revision ); + [[eosio::action]] void updtrevision( uint8_t revision ); /** - * Bid name action. Allows an account `bidder` to place a bid for a name `newname`. - * @param bidder - the account placing the bid, - * @param newname - the name the bid is placed for, - * @param bid - the amount of system tokens payed for the bid. + * \details Bid name action. Allows an account `bidder` to place a bid for a name `newname`. + * \param bidder The account placing the bid. + * \param newname The name the bid is placed for. + * \param bid The amount of system tokens payed for the bid. * - * @pre Bids can be placed only on top-level suffix, - * @pre Non empty name, - * @pre Names longer than 12 chars are not allowed, - * @pre Names equal with 12 chars can be created without placing a bid, - * @pre Bid has to be bigger than zero, - * @pre Bid's symbol must be system token, - * @pre Bidder account has to be different than current highest bidder, - * @pre Bid must increase current bid by 10%, - * @pre Auction must still be opened. + * \preconditions Bids can be placed only on top-level suffix. + * Non empty name. + * Names longer than 12 chars are not allowed. + * Names equal with 12 chars can be created without placing a bid. + * Bid has to be bigger than zero. + * Bid's symbol must be system token. + * Bidder account has to be different than current highest bidder. + * Bid must increase current bid by 10%. + * Auction must still be opened. */ - [[eosio::action]] - void bidname( const name& bidder, const name& newname, const asset& bid ); + [[eosio::action]] void bidname( const name& bidder, + const name& newname, + const asset& bid ); /** - * Bid refund action. Allows the account `bidder` to get back the amount it bid so far on a `newname` name. + * \details Bid refund action. Allows the account `bidder` to get back the amount it bid so far on a `newname` name. * - * @param bidder - the account that gets refunded, - * @param newname - the name for which the bid was placed and now it gets refunded for. + * \param bidder The account that gets refunded. + * \param newname The name for which the bid was placed and now it gets refunded for. */ - [[eosio::action]] - void bidrefund( const name& bidder, const name& newname ); + [[eosio::action]] void bidrefund( const name& bidder, const name& newname ); /** - * Change the annual inflation rate of the core token supply and specify how + * \details Change the annual inflation rate of the core token supply and specify how * the new issued tokens will be distributed based on the following structure. - * - * @param annual_rate - Annual inflation rate of the core token supply. + * \param annual_rate - Annual inflation rate of the core token supply. * (eg. For 5% Annual inflation => annual_rate=500 * For 1.5% Annual inflation => annual_rate=150 * - * @param inflation_pay_factor - Inverse of the fraction of the inflation used to reward block producers. + * \param inflation_pay_factor - Inverse of the fraction of the inflation used to reward block producers. * The remaining inflation will be sent to the `eosio.saving` account. * (eg. For 20% of inflation going to block producer rewards => inflation_pay_factor = 50000 * For 100% of inflation going to block producer rewards => inflation_pay_factor = 10000). * - * @param votepay_factor - Inverse of the fraction of the block producer rewards to be distributed proportional to blocks produced. + * \param votepay_factor - Inverse of the fraction of the block producer rewards to be distributed proportional to blocks produced. * The remaining rewards will be distributed proportional to votes received. * (eg. For 25% of block producer rewards going towards block pay => votepay_factor = 40000 * For 75% of block producer rewards going towards block pay => votepay_factor = 13333). */ - [[eosio::action]] - void setinflation( int64_t annual_rate, int64_t inflation_pay_factor, int64_t votepay_factor ); + [[eosio::action]] void setinflation( int64_t annual_rate, + int64_t inflation_pay_factor, + int64_t votepay_factor ); using init_action = eosio::action_wrapper<"init"_n, &system_contract::init>; using setacctram_action = eosio::action_wrapper<"setacctram"_n, &system_contract::setacctram>; diff --git a/contracts/eosio.system/include/eosio.system/exchange_state.hpp b/contracts/eosio.system/include/eosio.system/exchange_state.hpp index b41a5dfe5..b6795ac2b 100644 --- a/contracts/eosio.system/include/eosio.system/exchange_state.hpp +++ b/contracts/eosio.system/include/eosio.system/exchange_state.hpp @@ -45,4 +45,4 @@ namespace eosiosystem { }; typedef eosio::multi_index< "rammarket"_n, exchange_state > rammarket; -} /// namespace eosiosystem +} // namespace eosiosystem diff --git a/contracts/eosio.system/include/eosio.system/native.hpp b/contracts/eosio.system/include/eosio.system/native.hpp index 58dfee079..eaf92d27b 100644 --- a/contracts/eosio.system/include/eosio.system/native.hpp +++ b/contracts/eosio.system/include/eosio.system/native.hpp @@ -18,9 +18,7 @@ namespace eosiosystem { using eosio::public_key; /** - * A weighted permission. - * - * @details Defines a weighted permission, that is a permission which has a weight associated. + * \details Defines a weighted permission, that is a permission which has a weight associated. * A permission is defined by an account name plus a permission name. */ struct permission_level_weight { @@ -32,9 +30,7 @@ namespace eosiosystem { }; /** - * Weighted key. - * - * @details A weighted key is defined by a public key and an associated weight. + * \details A weighted key is defined by a public key and an associated weight. */ struct key_weight { eosio::public_key key; @@ -45,9 +41,7 @@ namespace eosiosystem { }; /** - * Wait weight. - * - * @details A wait weight is defined by a number of seconds to wait for and a weight. + * \details A wait weight is defined by a number of seconds to wait for and a weight. */ struct wait_weight { uint32_t wait_sec; @@ -58,9 +52,7 @@ namespace eosiosystem { }; /** - * Blockchain authority. - * - * @details An authority is defined by: + * \details An authority is defined by: * - a vector of key_weights (a key_weight is a public key plus a wieght), * - a vector of permission_level_weights, (a permission_level is an account name plus a permission name) * - a vector of wait_weights (a wait_weight is defined by a number of seconds to wait and a weight) @@ -77,11 +69,9 @@ namespace eosiosystem { }; /** - * Blockchain block header. - * - * @details A block header is defined by: + * \details A block header is defined by: * - a timestamp, - * - the producer that created it, + * The producer that created it, * - a confirmed flag default as zero, * - a link to previous block, * - a link to the transaction merkel root, @@ -105,9 +95,7 @@ namespace eosiosystem { }; /** - * abi_hash - * - * @details abi_hash is the structure underlying the abihash table and consists of: + * \details abi_hash is the structure underlying the abihash table and consists of: * - `owner`: the account owner of the contract's abi * - `hash`: is the sha256 hash of the abi/binary */ @@ -121,9 +109,7 @@ namespace eosiosystem { // Method parameters commented out to prevent generation of code that parses input data. /** - * The EOSIO core native contract that governs authorization and contracts' abi. - * - * @details + * \details The EOSIO core native contract that governs authorization and contracts' abi. */ class [[eosio::contract("eosio.system")]] native : public eosio::contract { public: @@ -131,20 +117,16 @@ namespace eosiosystem { using eosio::contract::contract; /** - * @{ - * These actions map one-on-one with the ones defined in - * [Native Action Handlers](@ref native_action_handlers) section. + * \output_section Native Actions + * The native actions map one-on-one with the ones defined in the blockchain core layer. * They are present here so they can show up in the abi file and thus user can send them * to this contract, but they have no specific implementation at this contract level, * they will execute the implementation at the core level and nothing else. - */ - /** - * New account action * - * @details Called after a new account is created. This code enforces resource-limits rules + * The `newaccount` action is called after a new account is created. This code enforces resource-limits rules * for new accounts as well as new account naming conventions. * - * 1. accounts cannot contain '.' symbols which forces all acccounts to be 12 + * 1. accounts cannot contain '.' symbols which forces all accounts to be 12 * characters long without '.' until a future account auction process is implemented * which prevents name squatting. * @@ -152,44 +134,33 @@ namespace eosiosystem { * therefore, this method will execute an inline buyram from receiver for newacnt in * an amount equal to the current new account creation fee. */ - [[eosio::action]] - void newaccount( const name& creator, - const name& name, - ignore owner, - ignore active); - + [[eosio::action]] void newaccount( const name& creator, + const name& name, + ignore owner, + ignore active); /** - * Update authorization action. - * - * @details Updates pemission for an account + * \details Updates permission for an account * - * @param account - the account for which the permission is updated - * @param pemission - the permission name which is updated - * @param parem - the parent of the permission which is updated - * @param aut - the json describing the permission authorization + * \param account The account for which the permission is updated. + * \param permission The permission name which is updated. + * \param parent The parent of the permission which is updated. + * \param auth The json describing the permission authorization. */ - [[eosio::action]] - void updateauth( ignore account, - ignore permission, - ignore parent, - ignore auth ) {} - + [[eosio::action]] void updateauth( ignore account, + ignore permission, + ignore parent, + ignore auth ) {} /** - * Delete authorization action. - * - * @details Deletes the authorization for an account's permision. + * \details Deletes the authorization for an account's permission. * - * @param account - the account for which the permission authorization is deleted, - * @param permission - the permission name been deleted. + * \param account The account for which the permission authorization is deleted. + * \param permission The permission name been deleted. */ - [[eosio::action]] - void deleteauth( ignore account, - ignore permission ) {} + [[eosio::action]] void deleteauth( ignore account, + ignore permission ) {} /** - * Link authorization action. - * - * @details Assigns a specific action from a contract to a permission you have created. Five system + * \details Assigns a specific action from a contract to a permission you have created. Five system * actions can not be linked `updateauth`, `deleteauth`, `linkauth`, `unlinkauth`, and `canceldelay`. * This is useful because when doing authorization checks, the EOSIO based blockchain starts with the * action needed to be authorized (and the contract belonging to), and looks up which permission @@ -198,80 +169,65 @@ namespace eosiosystem { * `eosio.any` is an implicit permission which exists on every account; you can link actions to `eosio.any` * and that will make it so linked actions are accessible to any permissions defined for the account. * - * @param account - the permission's owner to be linked and the payer of the RAM needed to store this link, - * @param code - the owner of the action to be linked, - * @param type - the action to be linked, - * @param requirement - the permission to be linked. + * \param account The permission's owner to be linked and the payer of the RAM needed to store this link. + * \param code The owner of the action to be linked. + * \param type The action to be linked. + * \param requirement The permission to be linked. */ - [[eosio::action]] - void linkauth( ignore account, - ignore code, - ignore type, - ignore requirement ) {} - + [[eosio::action]] void linkauth( ignore account, + ignore code, + ignore type, + ignore requirement ) {} /** - * Unlink authorization action. + * \details It's doing the reverse of linkauth action, by unlinking the given action. * - * @details It's doing the reverse of linkauth action, by unlinking the given action. - * - * @param account - the owner of the permission to be unlinked and the receiver of the freed RAM, - * @param code - the owner of the action to be unlinked, - * @param type - the action to be unlinked. + * \param account The owner of the permission to be unlinked and the receiver of the freed RAM. + * \param code The owner of the action to be unlinked. + * \param type The action to be unlinked. */ - [[eosio::action]] - void unlinkauth( ignore account, - ignore code, - ignore type ) {} - + [[eosio::action]] void unlinkauth( ignore account, + ignore code, + ignore type ) {} /** - * Cancel delay action. + * \details Cancels a deferred transaction. * - * @details Cancels a deferred transaction. - * - * @param canceling_auth - the permission that authorizes this action, - * @param trx_id - the deferred transaction id to be cancelled. + * \param canceling_auth The permission that authorizes this action. + * \param trx_id The deferred transaction id to be cancelled. */ - [[eosio::action]] - void canceldelay( ignore canceling_auth, ignore trx_id ) {} + [[eosio::action]] void canceldelay( ignore canceling_auth, + ignore trx_id ) {} /** - * On error action. - * - * @details Notification of this action is delivered to the sender of a deferred transaction + * \details Notification of this action is delivered to the sender of a deferred transaction * when an objective error occurs while executing the deferred transaction. * This action is not meant to be called directly. * - * @param sender_id - the id for the deferred transaction chosen by the sender, - * @param sent_trx - the deferred transaction that failed. + * \param sender_id The id for the deferred transaction chosen by the sender, + * \param sent_trx The deferred transaction that failed. */ - [[eosio::action]] - void onerror( ignore sender_id, ignore> sent_trx ); + [[eosio::action]] void onerror( ignore sender_id, + ignore> sent_trx ); /** - * Set abi action. + * \details Sets the contract abi for an account. * - * @details Sets the contract abi for an account. - * - * @param account - the account for which to set the contract abi. - * @param abi - the abi content to be set, in the form of a blob binary. + * \param account The account for which to set the contract abi. + * \param abi The abi content to be set, in the form of a blob binary. */ - [[eosio::action]] - void setabi( const name& account, const std::vector& abi ); + [[eosio::action]] void setabi( const name& account, const std::vector& abi ); /** - * Set code action. - * - * @details Sets the contract code for an account. + * \details Sets the contract code for an account. * - * @param account - the account for which to set the contract code. - * @param vmtype - reserved, set it to zero. - * @param vmversion - reserved, set it to zero. - * @param code - the code content to be set, in the form of a blob binary.. + * \param account The account for which to set the contract code. + * \param vmtype Reserved, set it to zero. + * \param vmversion Reserved, set it to zero. + * \param code The code content to be set, in the form of a blob binary. */ - [[eosio::action]] - void setcode( const name& account, uint8_t vmtype, uint8_t vmversion, const std::vector& code ) {} - - /** @}*/ + [[eosio::action]] void setcode( const name& account, + uint8_t vmtype, + uint8_t vmversion, + const std::vector& code ) {} using newaccount_action = eosio::action_wrapper<"newaccount"_n, &native::newaccount>; using updateauth_action = eosio::action_wrapper<"updateauth"_n, &native::updateauth>; @@ -282,5 +238,4 @@ namespace eosiosystem { using setcode_action = eosio::action_wrapper<"setcode"_n, &native::setcode>; using setabi_action = eosio::action_wrapper<"setabi"_n, &native::setabi>; }; - /** @}*/ // @addtogroup eosiosystem } diff --git a/contracts/eosio.system/include/eosio.system/rex.results.hpp b/contracts/eosio.system/include/eosio.system/rex.results.hpp index 378d6add3..fb051c15d 100644 --- a/contracts/eosio.system/include/eosio.system/rex.results.hpp +++ b/contracts/eosio.system/include/eosio.system/rex.results.hpp @@ -9,7 +9,7 @@ using eosio::asset; using eosio::name; /** - * The actions `buyresult`, `sellresult`, `rentresult`, and `orderresult` of `rex.results` are all no-ops. + * \details The actions `buyresult`, `sellresult`, `rentresult`, and `orderresult` of `rex.results` are all no-ops. * They are added as inline convenience actions to `rentnet`, `rentcpu`, `buyrex`, `unstaketorex`, and `sellrex`. * An inline convenience action does not have any effect, however, * its data includes the result of the parent action and appears in its trace. @@ -20,37 +20,33 @@ class [[eosio::contract("rex.results")]] rex_results : eosio::contract { using eosio::contract::contract; /** - * Buyresult action. + * \details Buyresult action. * - * @param rex_received - amount of tokens used in buy order + * \param rex_received - amount of tokens used in buy order */ - [[eosio::action]] - void buyresult( const asset& rex_received ); + [[eosio::action]] void buyresult( const asset& rex_received ); /** - * Sellresult action. + * \details Sellresult action. * - * @param proceeds - amount of tokens used in sell order + * \param proceeds - amount of tokens used in sell order */ - [[eosio::action]] - void sellresult( const asset& proceeds ); + [[eosio::action]] void sellresult( const asset& proceeds ); /** - * Orderresult action. + * \details Orderresult action. * - * @param owner - the owner of the order - * @param proceeds - amount of tokens used in order + * \param owner - the owner of the order + * \param proceeds - amount of tokens used in order */ - [[eosio::action]] - void orderresult( const name& owner, const asset& proceeds ); + [[eosio::action]] void orderresult( const name& owner, const asset& proceeds ); /** - * Rentresult action. + * \details Rentresult action. * - * @param rented_tokens - amount of rented tokens + * \param rented_tokens - amount of rented tokens */ - [[eosio::action]] - void rentresult( const asset& rented_tokens ); + [[eosio::action]] void rentresult( const asset& rented_tokens ); using buyresult_action = action_wrapper<"buyresult"_n, &rex_results::buyresult>; using sellresult_action = action_wrapper<"sellresult"_n, &rex_results::sellresult>; diff --git a/contracts/eosio.system/src/delegate_bandwidth.cpp b/contracts/eosio.system/src/delegate_bandwidth.cpp index d15a8202a..068a9ecbf 100644 --- a/contracts/eosio.system/src/delegate_bandwidth.cpp +++ b/contracts/eosio.system/src/delegate_bandwidth.cpp @@ -22,9 +22,8 @@ namespace eosiosystem { using eosio::time_point_sec; using eosio::token; - /** - * This action will buy an exact amount of ram and bill the payer the current market price. - */ + + // This action will buy an exact amount of ram and bill the payer the current market price. void system_contract::buyrambytes( const name& payer, const name& receiver, uint32_t bytes ) { auto itr = _rammarket.find(ramcore_symbol.raw()); const int64_t ram_reserve = itr->base.balance.amount; @@ -35,14 +34,12 @@ namespace eosiosystem { } - /** - * When buying ram the payer irreversiblly transfers quant to system contract and only - * the receiver may reclaim the tokens via the sellram action. The receiver pays for the - * storage of all database records associated with this action. - * - * RAM is a scarce resource whose supply is defined by global properties max_ram_size. RAM is - * priced using the bancor algorithm such that price-per-byte with a constant reserve ratio of 100:1. - */ + + // When buying ram the payer irreversiblly transfers quant to system contract and only + // the receiver may reclaim the tokens via the sellram action. The receiver pays for the + // storage of all database records associated with this action. + // RAM is a scarce resource whose supply is defined by global properties max_ram_size. RAM is + // priced using the bancor algorithm such that price-per-byte with a constant reserve ratio of 100:1. void system_contract::buyram( const name& payer, const name& receiver, const asset& quant ) { require_auth( payer ); @@ -52,7 +49,7 @@ namespace eosiosystem { check( quant.amount > 0, "must purchase a positive amount" ); auto fee = quant; - fee.amount = ( fee.amount + 199 ) / 200; /// .5% fee (round up) + fee.amount = ( fee.amount + 199 ) / 200; // .5% fee (round up) // fee.amount cannot be 0 since that is only possible if quant.amount is 0 which is not allowed by the assert above. // If quant.amount == 1, then fee.amount == 1, // otherwise if quant.amount > 1, then 0 < fee.amount < quant.amount. @@ -105,12 +102,10 @@ namespace eosiosystem { } } - /** - * The system contract now buys and sells RAM allocations at prevailing market prices. - * This may result in traders buying RAM today in anticipation of potential shortages - * tomorrow. Overall this will result in the market balancing the supply and demand - * for RAM over time. - */ + // The system contract now buys and sells RAM allocations at prevailing market prices. + // This may result in traders buying RAM today in anticipation of potential shortages + // tomorrow. Overall this will result in the market balancing the supply and demand + // for RAM over time. void system_contract::sellram( const name& account, int64_t bytes ) { require_auth( account ); update_ram_supply(); @@ -125,7 +120,7 @@ namespace eosiosystem { asset tokens_out; auto itr = _rammarket.find(ramcore_symbol.raw()); _rammarket.modify( itr, same_payer, [&]( auto& es ) { - /// the cast to int64_t of bytes is safe because we certify bytes is <= quota which is limited by prior purchases + // the cast to int64_t of bytes is safe because we certify bytes is <= quota which is limited by prior purchases tokens_out = es.direct_convert( asset(bytes, ram_symbol), core_symbol()); }); @@ -134,7 +129,7 @@ namespace eosiosystem { _gstate.total_ram_bytes_reserved -= static_cast(bytes); // bytes > 0 is asserted above _gstate.total_ram_stake -= tokens_out.amount; - //// this shouldn't happen, but just in case it does we should prevent it + // this shouldn't happen, but just in case it does we should prevent it check( _gstate.total_ram_stake >= 0, "error, attempt to unstake more tokens than previously staked" ); userres.modify( res_itr, account, [&]( auto& res ) { @@ -152,7 +147,7 @@ namespace eosiosystem { token::transfer_action transfer_act{ token_account, { {ram_account, active_permission}, {account, active_permission} } }; transfer_act.send( ram_account, account, asset(tokens_out), "sell ram" ); } - auto fee = ( tokens_out.amount + 199 ) / 200; /// .5% fee (round up) + auto fee = ( tokens_out.amount + 199 ) / 200; // .5% fee (round up) // since tokens_out.amount was asserted to be at least 2 earlier, fee.amount < tokens_out.amount if ( fee > 0 ) { token::transfer_action transfer_act{ token_account, { {account, active_permission} } }; @@ -162,7 +157,7 @@ namespace eosiosystem { } void validate_b1_vesting( int64_t stake ) { - const int64_t base_time = 1527811200; /// 2018-06-01 + const int64_t base_time = 1527811200; // 2018-06-01 const int64_t max_claimable = 100'000'000'0000ll; const int64_t claimable = int64_t(max_claimable * double(current_time_point().sec_since_epoch() - base_time) / (10*seconds_per_year) ); @@ -321,7 +316,7 @@ namespace eosiosystem { }); need_deferred_trx = true; } // else stake increase requested with no existing row in refunds_tbl -> nothing to do with refunds_tbl - } /// end if is_delegating_to_self || is_undelegating + } // end if is_delegating_to_self || is_undelegating if ( need_deferred_trx ) { eosio::transaction out; @@ -413,4 +408,4 @@ namespace eosiosystem { } -} //namespace eosiosystem +} // namespace eosiosystem diff --git a/contracts/eosio.system/src/eosio.system.cpp b/contracts/eosio.system/src/eosio.system.cpp index 202210c7d..1c58d7e08 100644 --- a/contracts/eosio.system/src/eosio.system.cpp +++ b/contracts/eosio.system/src/eosio.system.cpp @@ -67,16 +67,14 @@ namespace eosiosystem { void system_contract::setram( uint64_t max_ram_size ) { require_auth( get_self() ); - check( _gstate.max_ram_size < max_ram_size, "ram may only be increased" ); /// decreasing ram might result market maker issues + check( _gstate.max_ram_size < max_ram_size, "ram may only be increased" ); // decreasing ram might result market maker issues check( max_ram_size < 1024ll*1024*1024*1024*1024, "ram size is unrealistic" ); check( max_ram_size > _gstate.total_ram_bytes_reserved, "attempt to set max below reserved" ); auto delta = int64_t(max_ram_size) - int64_t(_gstate.max_ram_size); auto itr = _rammarket.find(ramcore_symbol.raw()); - /** - * Increase the amount of ram for sale based upon the change in max ram size. - */ + // Increase the amount of ram for sale based upon the change in max ram size. _rammarket.modify( itr, same_payer, [&]( auto& m ) { m.base.balance.amount += delta; }); @@ -93,9 +91,7 @@ namespace eosiosystem { auto new_ram = (cbt.slot - _gstate2.last_ram_increase.slot)*_gstate2.new_ram_per_block; _gstate.max_ram_size += new_ram; - /** - * Increase the amount of ram for sale based upon the change in max ram size. - */ + // Increase the amount of ram for sale based upon the change in max ram size. _rammarket.modify( itr, same_payer, [&]( auto& m ) { m.base.balance.amount += new_ram; }); @@ -310,15 +306,11 @@ namespace eosiosystem { _global4.set( _gstate4, get_self() ); } - /** - * Called after a new account is created. This code enforces resource-limits rules - * for new accounts as well as new account naming conventions. - * - * Account names containing '.' symbols must have a suffix equal to the name of the creator. - * This allows users who buy a premium name (shorter than 12 characters with no dots) to be the only ones - * who can create accounts with the creator's name as a suffix. - * - */ + // Called after a new account is created. This code enforces resource-limits rules + // for new accounts as well as new account naming conventions. + // Account names containing '.' symbols must have a suffix equal to the name of the creator. + // This allows users who buy a premium name (shorter than 12 characters with no dots) to be the only ones + // who can create accounts with the creator's name as a suffix. void native::newaccount( const name& creator, const name& newact, ignore owner, @@ -397,4 +389,4 @@ namespace eosiosystem { open_act.send( rex_account, core, get_self() ); } -} /// eosio.system +} // eosio.system diff --git a/contracts/eosio.system/src/exchange_state.cpp b/contracts/eosio.system/src/exchange_state.cpp index 8f9734bcb..f7f5bba4f 100644 --- a/contracts/eosio.system/src/exchange_state.cpp +++ b/contracts/eosio.system/src/exchange_state.cpp @@ -107,4 +107,4 @@ namespace eosiosystem { return inp; } -} /// namespace eosiosystem +} // namespace eosiosystem diff --git a/contracts/eosio.system/src/producer_pay.cpp b/contracts/eosio.system/src/producer_pay.cpp index 4db2f7740..8a20c1b3e 100644 --- a/contracts/eosio.system/src/producer_pay.cpp +++ b/contracts/eosio.system/src/producer_pay.cpp @@ -21,18 +21,16 @@ namespace eosiosystem { // is eventually completely removed, at which point this line can be removed. _gstate2.last_block_num = timestamp; - /** until activation, no new rewards are paid */ + // until activation, no new rewards are paid if( _gstate.thresh_activated_stake_time == time_point() ) return; - if( _gstate.last_pervote_bucket_fill == time_point() ) /// start the presses + if( _gstate.last_pervote_bucket_fill == time_point() ) // start the presses _gstate.last_pervote_bucket_fill = current_time_point(); - /** - * At startup the initial producer may not be one that is registered / elected - * and therefore there may be no producer object for them. - */ + // At startup the initial producer may not be one that is registered / elected and + // therefore there may be no producer object for them. auto prod = _producers.find( producer.value ); if ( prod != _producers.end() ) { _gstate.total_unpaid_blocks++; @@ -41,7 +39,7 @@ namespace eosiosystem { }); } - /// only update block producers once every minute, block_timestamp is in half seconds + // only update block producers once every minute, block_timestamp is in half seconds if( timestamp.slot - _gstate.last_producer_schedule_update.slot > 120 ) { update_elected_producers( timestamp ); @@ -118,8 +116,8 @@ namespace eosiosystem { auto prod2 = _producers2.find( owner.value ); - /// New metric to be used in pervote pay calculation. Instead of vote weight ratio, we combine vote weight and - /// time duration the vote weight has been held into one metric. + // New metric to be used in pervote pay calculation. Instead of vote weight ratio, we combine vote weight and + // time duration the vote weight has been held into one metric. const auto last_claim_plus_3days = prod.last_claim_time + microseconds(3 * useconds_per_day); bool crossed_threshold = (last_claim_plus_3days <= ct); @@ -188,4 +186,4 @@ namespace eosiosystem { } } -} //namespace eosiosystem +} // namespace eosiosystem diff --git a/contracts/eosio.system/src/rex.cpp b/contracts/eosio.system/src/rex.cpp index 8e9d881f3..32b50b705 100644 --- a/contracts/eosio.system/src/rex.cpp +++ b/contracts/eosio.system/src/rex.cpp @@ -115,10 +115,9 @@ namespace eosiosystem { if ( from == "b1"_n ) { check( false, "b1 sellrex orders should not be queued" ); } - /** - * REX order couldn't be filled and is added to queue. - * If account already has an open order, requested rex is added to existing order. - */ + + // REX order couldn't be filled and is added to queue. + // If account already has an open order, requested rex is added to existing order. auto oitr = _rexorders.find( from.value ); if ( oitr == _rexorders.end() ) { oitr = _rexorders.emplace( from, [&]( auto& order ) { @@ -325,7 +324,7 @@ namespace eosiosystem { update_rex_account( owner, asset( 0, core_symbol() ), asset( 0, core_symbol() ) ); - /// check for any outstanding loans or rex fund + // check for any outstanding loans or rex fund { rex_cpu_loan_table cpu_loans( get_self(), get_self().value ); auto cpu_idx = cpu_loans.get_index<"byowner"_n>(); @@ -343,7 +342,7 @@ namespace eosiosystem { } } - /// check for remaining rex balance + // check for remaining rex balance { auto rex_itr = _rexbalance.find( owner.value ); if ( rex_itr != _rexbalance.end() ) { @@ -354,12 +353,12 @@ namespace eosiosystem { } /** - * @brief Updates account NET and CPU resource limits + * \details Updates account NET and CPU resource limits * - * @param from - account charged for RAM if there is a need - * @param receiver - account whose resource limits are updated - * @param delta_net - change in NET bandwidth limit - * @param delta_cpu - change in CPU bandwidth limit + * \param from - account charged for RAM if there is a need + * \param receiver - account whose resource limits are updated + * \param delta_net - change in NET bandwidth limit + * \param delta_cpu - change in CPU bandwidth limit */ void system_contract::update_resource_limits( const name& from, const name& receiver, int64_t delta_net, int64_t delta_cpu ) { @@ -412,10 +411,10 @@ namespace eosiosystem { } /** - * @brief Checks if account satisfies voting requirement (voting for a proxy or 21 producers) + * \details Checks if account satisfies voting requirement (voting for a proxy or 21 producers) * for buying REX * - * @param owner - account buying or already holding REX tokens + * \param owner - account buying or already holding REX tokens * @err_msg - error message */ void system_contract::check_voting_requirement( const name& owner, const char* error_msg )const @@ -425,7 +424,7 @@ namespace eosiosystem { } /** - * @brief Checks if CPU and Network loans are available + * \details Checks if CPU and Network loans are available * * Loans are available if 1) REX pool lendable balance is nonempty, and 2) there are no * unfilled sellrex orders. @@ -445,11 +444,11 @@ namespace eosiosystem { } /** - * @brief Updates rex_pool balances upon creating a new loan or renewing an existing one + * \details Updates rex_pool balances upon creating a new loan or renewing an existing one * - * @param payment - loan fee paid - * @param rented_tokens - amount of tokens to be staked to loan receiver - * @param new_loan - flag indicating whether the loan is new or being renewed + * \param payment - loan fee paid + * \param rented_tokens - amount of tokens to be staked to loan receiver + * \param new_loan - flag indicating whether the loan is new or being renewed */ void system_contract::add_loan_to_rex_pool( const asset& payment, int64_t rented_tokens, bool new_loan ) { @@ -468,9 +467,9 @@ namespace eosiosystem { } /** - * @brief Updates rex_pool balances upon closing an expired loan + * \details Updates rex_pool balances upon closing an expired loan * - * @param loan - loan to be closed + * \param loan - loan to be closed */ void system_contract::remove_loan_from_rex_pool( const rex_loan& loan ) { @@ -489,7 +488,7 @@ namespace eosiosystem { } /** - * @brief Updates the fields of an existing loan that is being renewed + * \details Updates the fields of an existing loan that is being renewed */ template int64_t system_contract::update_renewed_loan( Index& idx, const Iterator& itr, int64_t rented_tokens ) @@ -504,9 +503,9 @@ namespace eosiosystem { } /** - * @brief Performs maintenance operations on expired NET and CPU loans and sellrex orders + * \details Performs maintenance operations on expired NET and CPU loans and sellrex orders * - * @param max - maximum number of each of the three categories to be processed + * \param max - maximum number of each of the three categories to be processed */ void system_contract::runrex( uint16_t max ) { @@ -517,27 +516,27 @@ namespace eosiosystem { const auto& pool = _rexpool.begin(); auto process_expired_loan = [&]( auto& idx, const auto& itr ) -> std::pair { - /// update rex_pool in order to delete existing loan + // update rex_pool in order to delete existing loan remove_loan_from_rex_pool( *itr ); bool delete_loan = false; int64_t delta_stake = 0; - /// calculate rented tokens at current price + // calculate rented tokens at current price int64_t rented_tokens = exchange_state::get_bancor_output( pool->total_rent.amount, pool->total_unlent.amount, itr->payment.amount ); - /// conditions for loan renewal - bool renew_loan = itr->payment <= itr->balance /// loan has sufficient balance - && itr->payment.amount < rented_tokens /// loan has favorable return - && rex_loans_available(); /// no pending sell orders + // conditions for loan renewal + bool renew_loan = itr->payment <= itr->balance // loan has sufficient balance + && itr->payment.amount < rented_tokens // loan has favorable return + && rex_loans_available(); // no pending sell orders if ( renew_loan ) { - /// update rex_pool in order to account for renewed loan + // update rex_pool in order to account for renewed loan add_loan_to_rex_pool( itr->payment, rented_tokens, false ); - /// update renewed loan fields + // update renewed loan fields delta_stake = update_renewed_loan( idx, itr, rented_tokens ); } else { delete_loan = true; delta_stake = -( itr->total_staked.amount ); - /// refund "from" account if the closed loan balance is positive + // refund "from" account if the closed loan balance is positive if ( itr->balance.amount > 0 ) { transfer_to_fund( itr->from, itr->balance ); } @@ -546,7 +545,7 @@ namespace eosiosystem { return { delete_loan, delta_stake }; }; - /// transfer from eosio.names to eosio.rex + // transfer from eosio.names to eosio.rex if ( pool->namebid_proceeds.amount > 0 ) { channel_to_rex( names_account, pool->namebid_proceeds ); _rexpool.modify( pool, same_payer, [&]( auto& rt ) { @@ -554,7 +553,7 @@ namespace eosiosystem { }); } - /// process cpu loans + // process cpu loans { rex_cpu_loan_table cpu_loans( get_self(), get_self().value ); auto cpu_idx = cpu_loans.get_index<"byexpr"_n>(); @@ -571,7 +570,7 @@ namespace eosiosystem { } } - /// process net loans + // process net loans { rex_net_loan_table net_loans( get_self(), get_self().value ); auto net_idx = net_loans.get_index<"byexpr"_n>(); @@ -588,7 +587,7 @@ namespace eosiosystem { } } - /// process sellrex orders + // process sellrex orders if ( _rexorders.begin() != _rexorders.end() ) { auto idx = _rexorders.get_index<"bytime"_n>(); auto oitr = idx.begin(); @@ -606,7 +605,7 @@ namespace eosiosystem { order.stake_change.amount = result.stake_change.amount; order.close(); }); - /// send dummy action to show owner and proceeds of filled sellrex order + // send dummy action to show owner and proceeds of filled sellrex order rex_results::orderresult_action order_act( rex_account, std::vector{ } ); order_act.send( order_owner, result.proceeds ); } @@ -618,7 +617,7 @@ namespace eosiosystem { } /** - * @brief Adds returns from the REX return pool to the REX pool + * \details Adds returns from the REX return pool to the REX pool */ void system_contract::update_rex_pool() { @@ -730,7 +729,7 @@ namespace eosiosystem { transfer_from_fund( from, payment + fund ); - const auto& pool = _rexpool.begin(); /// already checked that _rexpool.begin() != _rexpool.end() in rex_loans_available() + const auto& pool = _rexpool.begin(); // already checked that _rexpool.begin() != _rexpool.end() in rex_loans_available() int64_t rented_tokens = exchange_state::get_bancor_output( pool->total_rent.amount, pool->total_unlent.amount, @@ -754,7 +753,7 @@ namespace eosiosystem { } /** - * @brief Processes a sellrex order and returns object containing the results + * \details Processes a sellrex order and returns object containing the results * * Processes an incoming or already scheduled sellrex order. If REX pool has enough core * tokens not frozen in loans, order is filled. In this case, REX pool totals, user rex_balance @@ -763,8 +762,8 @@ namespace eosiosystem { * different function to complete order processing, i.e. transfer proceeds to user REX fund and * update user vote weight. * - * @param bitr - iterator pointing to rex_balance database record - * @param rex - amount of rex to be sold + * \param bitr - iterator pointing to rex_balance database record + * \param rex - amount of rex to be sold * * @return rex_order_outcome - a struct containing success flag, order proceeds, and resultant * vote stake change @@ -833,12 +832,12 @@ namespace eosiosystem { } /** - * @brief Transfers tokens from owner REX fund + * \details Transfers tokens from owner REX fund * * @pre - owner REX fund has sufficient balance * - * @param owner - owner account name - * @param amount - tokens to be transfered out of REX fund + * \param owner - owner account name + * \param amount - tokens to be transfered out of REX fund */ void system_contract::transfer_from_fund( const name& owner, const asset& amount ) { @@ -851,10 +850,10 @@ namespace eosiosystem { } /** - * @brief Transfers tokens to owner REX fund + * \details Transfers tokens to owner REX fund * - * @param owner - owner account name - * @param amount - tokens to be transfered to REX fund + * \param owner - owner account name + * \param amount - tokens to be transfered to REX fund */ void system_contract::transfer_to_fund( const name& owner, const asset& amount ) { @@ -873,17 +872,17 @@ namespace eosiosystem { } /** - * @brief Processes owner filled sellrex order and updates vote weight + * \details Processes owner filled sellrex order and updates vote weight * * Checks if user has a scheduled sellrex order that has been filled, completes its processing, * and deletes it. Processing entails transfering proceeds to user REX fund and updating user * vote weight. Additional proceeds and stake change can be passed as arguments. This function * is called only by actions pushed by owner. * - * @param owner - owner account name - * @param proceeds - additional proceeds to be transfered to owner REX fund - * @param delta_stake - additional stake to be added to owner vote weight - * @param force_vote_update - if true, vote weight is updated even if vote stake didn't change + * \param owner - owner account name + * \param proceeds - additional proceeds to be transfered to owner REX fund + * \param delta_stake - additional stake to be added to owner vote weight + * \param force_vote_update - if true, vote weight is updated even if vote stake didn't change * * @return asset - REX amount of owner unfilled sell order if one exists */ @@ -912,10 +911,10 @@ namespace eosiosystem { } /** - * @brief Channels system fees to REX pool + * \details Channels system fees to REX pool * - * @param from - account from which asset is transfered to REX pool - * @param amount - amount of tokens to be transfered + * \param from - account from which asset is transfered to REX pool + * \param amount - amount of tokens to be transfered */ void system_contract::channel_to_rex( const name& from, const asset& amount ) { @@ -931,9 +930,9 @@ namespace eosiosystem { } /** - * @brief Updates namebid proceeds to be transfered to REX pool + * \details Updates namebid proceeds to be transfered to REX pool * - * @param highest_bid - highest bidding amount of closed namebid + * \param highest_bid - highest bidding amount of closed namebid */ void system_contract::channel_namebid_to_rex( const int64_t highest_bid ) { @@ -947,7 +946,7 @@ namespace eosiosystem { } /** - * @brief Calculates maturity time of purchased REX tokens which is 4 days from end + * \details Calculates maturity time of purchased REX tokens which is 4 days from end * of the day UTC * * @return time_point_sec @@ -962,9 +961,9 @@ namespace eosiosystem { } /** - * @brief Updates REX owner maturity buckets + * \details Updates REX owner maturity buckets * - * @param bitr - iterator pointing to rex_balance object + * \param bitr - iterator pointing to rex_balance object */ void system_contract::process_rex_maturities( const rex_balance_table::const_iterator& bitr ) { @@ -978,10 +977,10 @@ namespace eosiosystem { } /** - * @brief Consolidates REX maturity buckets into one + * \details Consolidates REX maturity buckets into one * - * @param bitr - iterator pointing to rex_balance object - * @param rex_in_sell_order - REX tokens in owner unfilled sell order, if one exists + * \param bitr - iterator pointing to rex_balance object + * \param rex_in_sell_order - REX tokens in owner unfilled sell order, if one exists */ void system_contract::consolidate_rex_balance( const rex_balance_table::const_iterator& bitr, const asset& rex_in_sell_order ) @@ -1002,28 +1001,27 @@ namespace eosiosystem { } /** - * @brief Updates REX pool balances upon REX purchase + * \details Updates REX pool balances upon REX purchase * - * @param payment - amount of core tokens paid + * \param payment - amount of core tokens paid * * @return asset - calculated amount of REX tokens purchased */ asset system_contract::add_to_rex_pool( const asset& payment ) { - /** - * If CORE_SYMBOL is (EOS,4), maximum supply is 10^10 tokens (10 billion tokens), i.e., maximum amount - * of indivisible units is 10^14. rex_ratio = 10^4 sets the upper bound on (REX,4) indivisible units to - * 10^18 and that is within the maximum allowable amount field of asset type which is set to 2^62 - * (approximately 4.6 * 10^18). For a different CORE_SYMBOL, and in order for maximum (REX,4) amount not - * to exceed that limit, maximum amount of indivisible units cannot be set to a value larger than 4 * 10^14. - * If precision of CORE_SYMBOL is 4, that corresponds to a maximum supply of 40 billion tokens. - */ + + // If CORE_SYMBOL is (EOS,4), maximum supply is 10^10 tokens (10 billion tokens), i.e., maximum amount + // of indivisible units is 10^14. rex_ratio = 10^4 sets the upper bound on (REX,4) indivisible units to + // 10^18 and that is within the maximum allowable amount field of asset type which is set to 2^62 + // (approximately 4.6 * 10^18). For a different CORE_SYMBOL, and in order for maximum (REX,4) amount not + // to exceed that limit, maximum amount of indivisible units cannot be set to a value larger than 4 * 10^14. + // If precision of CORE_SYMBOL is 4, that corresponds to a maximum supply of 40 billion tokens. const int64_t rex_ratio = 10000; - const asset init_total_rent( 20'000'0000, core_symbol() ); /// base balance prevents renting profitably until at least a minimum number of core_symbol() is made available + const asset init_total_rent( 20'000'0000, core_symbol() ); // base balance prevents renting profitably until at least a minimum number of core_symbol() is made available asset rex_received( 0, rex_symbol ); auto itr = _rexpool.begin(); if ( !rex_system_initialized() ) { - /// initialize REX pool + // initialize REX pool _rexpool.emplace( get_self(), [&]( auto& rp ) { rex_received.amount = payment.amount * rex_ratio; rp.total_lendable = payment; @@ -1033,7 +1031,7 @@ namespace eosiosystem { rp.total_rex = rex_received; rp.namebid_proceeds = asset( 0, core_symbol() ); }); - } else if ( !rex_available() ) { /// should be a rare corner case, REX pool is initialized but empty + } else if ( !rex_available() ) { // should be a rare corner case, REX pool is initialized but empty _rexpool.modify( itr, same_payer, [&]( auto& rp ) { rex_received.amount = payment.amount * rex_ratio; rp.total_lendable.amount = payment.amount; @@ -1043,7 +1041,7 @@ namespace eosiosystem { rp.total_rex.amount = rex_received.amount; }); } else { - /// total_lendable > 0 if total_rex > 0 except in a rare case and due to rounding errors + // total_lendable > 0 if total_rex > 0 except in a rare case and due to rounding errors check( itr->total_lendable.amount > 0, "lendable REX pool is empty" ); const int64_t S0 = itr->total_lendable.amount; const int64_t S1 = S0 + payment.amount; @@ -1062,9 +1060,9 @@ namespace eosiosystem { } /** - * @brief Adds an amount of core tokens to the REX return pool + * \details Adds an amount of core tokens to the REX return pool * - * @param fee - amount to be added + * \param fee - amount to be added */ void system_contract::add_to_rex_return_pool( const asset& fee ) { @@ -1098,11 +1096,11 @@ namespace eosiosystem { } /** - * @brief Updates owner REX balance upon buying REX tokens + * \details Updates owner REX balance upon buying REX tokens * - * @param owner - account name of REX owner - * @param payment - amount core tokens paid to buy REX - * @param rex_received - amount of purchased REX tokens + * \param owner - account name of REX owner + * \param payment - amount core tokens paid to buy REX + * \param rex_received - amount of purchased REX tokens * * @return asset - change in owner REX vote stake */ @@ -1143,13 +1141,13 @@ namespace eosiosystem { } /** - * @brief Reads amount of REX in savings bucket and removes the bucket from maturities + * \details Reads amount of REX in savings bucket and removes the bucket from maturities * * Reads and (temporarily) removes REX savings bucket from REX maturities in order to * allow uniform processing of remaining buckets as savings is a special case. This * function is used in conjunction with put_rex_savings. * - * @param bitr - iterator pointing to rex_balance object + * \param bitr - iterator pointing to rex_balance object * * @return int64_t - amount of REX in savings bucket */ @@ -1167,10 +1165,10 @@ namespace eosiosystem { } /** - * @brief Adds a specified REX amount to savings bucket + * \details Adds a specified REX amount to savings bucket * - * @param bitr - iterator pointing to rex_balance object - * @param rex - amount of REX to be added + * \param bitr - iterator pointing to rex_balance object + * \param rex - amount of REX to be added */ void system_contract::put_rex_savings( const rex_balance_table::const_iterator& bitr, int64_t rex ) { @@ -1186,9 +1184,9 @@ namespace eosiosystem { } /** - * @brief Updates voter REX vote stake to the current value of REX tokens held + * \details Updates voter REX vote stake to the current value of REX tokens held * - * @param voter - account name of voter + * \param voter - account name of voter */ void system_contract::update_rex_stake( const name& voter ) { @@ -1215,4 +1213,4 @@ namespace eosiosystem { } } -}; /// namespace eosiosystem +}; // namespace eosiosystem diff --git a/contracts/eosio.system/src/voting.cpp b/contracts/eosio.system/src/voting.cpp index a42239db5..eba89356f 100644 --- a/contracts/eosio.system/src/voting.cpp +++ b/contracts/eosio.system/src/voting.cpp @@ -148,7 +148,7 @@ namespace eosiosystem { } double stake2vote( int64_t staked ) { - /// TODO subtract 2080 brings the large numbers closer to this decade + // TODO subtract 2080 brings the large numbers closer to this decade double weight = int64_t( (current_time_point().sec_since_epoch() - (block_timestamp::block_timestamp_epoch / 1000)) / (seconds_per_day * 7) ) / double( 52 ); return double(staked) * std::pow( 2, weight ); } @@ -227,14 +227,12 @@ namespace eosiosystem { } auto voter = _voters.find( voter_name.value ); - check( voter != _voters.end(), "user must stake before they can vote" ); /// staking creates voter object + check( voter != _voters.end(), "user must stake before they can vote" ); // staking creates voter object check( !proxy || !voter->is_proxy, "account registered as a proxy is not allowed to use a proxy" ); - /** - * The first time someone votes we calculate and set last_vote_weight. Since they cannot unstake until - * after the chain has been activated, we can use last_vote_weight to determine that this is - * their first vote and should consider their stake activated. - */ + // The first time someone votes we calculate and set last_vote_weight. Since they cannot unstake until + // after the chain has been activated, we can use last_vote_weight to determine that this is + // their first vote and should consider their stake activated. if( _gstate.thresh_activated_stake_time == time_point() && voter->last_vote_weight <= 0.0 ) { _gstate.total_activated_stake += voter->staked; if( _gstate.total_activated_stake >= min_activated_stake ) { @@ -365,7 +363,7 @@ namespace eosiosystem { new_weight += voter.proxied_vote_weight; } - /// don't propagate small changes (1 ~= epsilon) + // don't propagate small changes (1 ~= epsilon) if ( fabs( new_weight - voter.last_vote_weight ) > 1 ) { if ( voter.proxy ) { auto& proxy = _voters.get( voter.proxy.value, "proxy not found" ); //data corruption @@ -417,4 +415,4 @@ namespace eosiosystem { ); } -} /// namespace eosiosystem +} // namespace eosiosystem diff --git a/contracts/eosio.token/include/eosio.token/eosio.token.hpp b/contracts/eosio.token/include/eosio.token/eosio.token.hpp index 050a685b5..541e64a24 100644 --- a/contracts/eosio.token/include/eosio.token/eosio.token.hpp +++ b/contracts/eosio.token/include/eosio.token/eosio.token.hpp @@ -14,12 +14,9 @@ namespace eosio { using std::string; /** - * The `eosio.token` sample system contract defines the structures and actions that allow users to create, issue, and manage tokens for EOSIO based blockchains. It demonstrates one way to implement a smart contract which allows for creation and management of tokens. It is possible for one to create a similar contract which suits different needs. However, it is recommended that if one only needs a token with the below listed actions, that one uses the `eosio.token` contract instead of developing their own. - * + * \details The `eosio.token` sample system contract defines the structures and actions that allow users to create, issue, and manage tokens for EOSIO based blockchains. It demonstrates one way to implement a smart contract which allows for creation and management of tokens. It is possible for one to create a similar contract which suits different needs. However, it is recommended that if one only needs a token with the below listed actions, that one uses the `eosio.token` contract instead of developing their own. * The `eosio.token` contract class also implements two useful public static methods: `get_supply` and `get_balance`. The first allows one to check the total supply of a specified token, created by an account and the second allows one to check the balance of a token for a specified account (the token creator account has to be specified as well). - * * The `eosio.token` contract manages the set of tokens, accounts and their corresponding balances, by using two internal multi-index structures: the `accounts` and `stats`. The `accounts` multi-index table holds, for each row, instances of `account` object and the `account` object holds information about the balance of one token. The `accounts` table is scoped to an eosio account, and it keeps the rows indexed based on the token's symbol. This means that when one queries the `accounts` multi-index table for an account name the result is all the tokens that account holds at the moment. - * * Similarly, the `stats` multi-index table, holds instances of `currency_stats` objects for each row, which contains information about current supply, maximum supply, and the creator account for a symbol token. The `stats` table is scoped to the token symbol. Therefore, when one queries the `stats` table for a token symbol the result is one single entry/row corresponding to the queried symbol token if it was previously created, or nothing, otherwise. */ class [[eosio::contract("eosio.token")]] token : public contract { @@ -27,88 +24,89 @@ namespace eosio { using contract::contract; /** - * Allows `issuer` account to create a token in supply of `maximum_supply`. If validation is successful a new entry in statstable for token symbol scope gets created. + * \details Allows `issuer` account to create a token in supply of `maximum_supply`. If validation is successful a new entry in statstable for token symbol scope gets created. * - * @param issuer - the account that creates the token, - * @param maximum_supply - the maximum supply set for the token created. + * \param issuer The account that creates the token. + * \param maximum_supply The maximum supply set for the token created. * - * @pre Token symbol has to be valid, - * @pre Token symbol must not be already created, - * @pre maximum_supply has to be smaller than the maximum supply allowed by the system: 1^62 - 1. - * @pre Maximum supply must be positive; + * \requires Token symbol has to be valid. + * \requires Token symbol must not be already created. + * \requires maximum_supply has to be smaller than the maximum supply allowed by the system: 1^62 - 1. + * \requires maximum_supply must be positive. */ - [[eosio::action]] - void create( const name& issuer, - const asset& maximum_supply); + [[eosio::action]] void create( const name& issuer, + const asset& maximum_supply); /** - * This action issues to `to` account a `quantity` of tokens. + * \details This action issues to `to` account a `quantity` of tokens. * - * @param to - the account to issue tokens to, it must be the same as the issuer, - * @param quntity - the amount of tokens to be issued, - * @memo - the memo string that accompanies the token issue transaction. + * \param to The account to issue tokens to, it must be the same as the issuer. + * \param quantity The amount of tokens to be issued. + * \param memo The memo string that accompanies the token issue transaction. */ - [[eosio::action]] - void issue( const name& to, const asset& quantity, const string& memo ); + [[eosio::action]] void issue( const name& to, + const asset& quantity, + const string& memo ); /** - * The opposite for create action, if all validations succeed, - * it debits the statstable.supply amount. + * \details The opposite for create action, if all validations succeed, it debits the statstable.supply amount. * - * @param quantity - the quantity of tokens to retire, - * @param memo - the memo string to accompany the transaction. + * \param quantity The quantity of tokens to retire. + * \param memo The memo string to accompany the transaction. */ - [[eosio::action]] - void retire( const asset& quantity, const string& memo ); + [[eosio::action]] void retire( const asset& quantity, + const string& memo ); /** - * Allows `from` account to transfer to `to` account the `quantity` tokens. - * One account is debited and the other is credited with quantity tokens. + * \details Allows `from` account to transfer to `to` account the `quantity` tokens. + * \effects One account is debited and the other is credited with quantity tokens. * - * @param from - the account to transfer from, - * @param to - the account to be transferred to, - * @param quantity - the quantity of tokens to be transferred, - * @param memo - the memo string to accompany the transaction. + * \param from The account to transfer from. + * \param to The account to be transferred to. + * \param quantity The quantity of tokens to be transferred. + * \param memo The memo string to accompany the transaction. */ - [[eosio::action]] - void transfer( const name& from, - const name& to, - const asset& quantity, - const string& memo ); + [[eosio::action]] void transfer( const name& from, + const name& to, + const asset& quantity, + const string& memo ); /** - * Allows `ram_payer` to create an account `owner` with zero balance for + * \details Allows `ram_payer` to create an account `owner` with zero balance for * token `symbol` at the expense of `ram_payer`. * - * @param owner - the account to be created, - * @param symbol - the token to be payed with by `ram_payer`, - * @param ram_payer - the account that supports the cost of this action. + * \param owner The account to be created. + * \param symbol The token to be payed with by `ram_payer`. + * \param ram_payer The account that supports the cost of this action. * - * More information can be read [here](https://github.com/EOSIO/eosio.contracts/issues/62) + * \notes More information can be read [here](https://github.com/EOSIO/eosio.contracts/issues/62) * and [here](https://github.com/EOSIO/eosio.contracts/issues/61). */ - [[eosio::action]] - void open( const name& owner, const symbol& symbol, const name& ram_payer ); + [[eosio::action]] void open( const name& owner, + const symbol& symbol, + const name& ram_payer ); /** - * This action is the opposite for open, it closes the account `owner` - * for token `symbol`. + * \details This action is the opposite for open, it closes the account `owner` for token `symbol`. * - * @param owner - the owner account to execute the close action for, - * @param symbol - the symbol of the token to execute the close action for. + * \param owner The owner account to execute the close action for. + * \param symbol The symbol of the token to execute the close action for. * - * @pre The pair of owner plus symbol has to exist otherwise no action is executed, - * @pre If the pair of owner plus symbol exists, the balance has to be zero. + * \preconditions The pair of owner plus symbol has to exist otherwise no action is executed. + * \preconditions If the pair of owner plus symbol exists, the balance has to be zero. */ - [[eosio::action]] - void close( const name& owner, const symbol& symbol ); + [[eosio::action]] void close( const name& owner, + const symbol& symbol ); - static asset get_supply( const name& token_contract_account, const symbol_code& sym_code ) + static asset get_supply( const name& token_contract_account, + const symbol_code& sym_code ) { stats statstable( token_contract_account, sym_code.raw() ); const auto& st = statstable.get( sym_code.raw() ); return st.supply; } - static asset get_balance( const name& token_contract_account, const name& owner, const symbol_code& sym_code ) + static asset get_balance( const name& token_contract_account, + const name& owner, + const symbol_code& sym_code ) { accounts accountstable( token_contract_account, owner.value ); const auto& ac = accountstable.get( sym_code.raw() ); diff --git a/contracts/eosio.token/src/eosio.token.cpp b/contracts/eosio.token/src/eosio.token.cpp index 8dda907e3..c226396b1 100644 --- a/contracts/eosio.token/src/eosio.token.cpp +++ b/contracts/eosio.token/src/eosio.token.cpp @@ -156,4 +156,4 @@ void token::close( const name& owner, const symbol& symbol ) acnts.erase( it ); } -} /// namespace eosio +} \ No newline at end of file diff --git a/contracts/eosio.wrap/include/eosio.wrap/eosio.wrap.hpp b/contracts/eosio.wrap/include/eosio.wrap/eosio.wrap.hpp index 8ed3fb8e2..fb3d69490 100644 --- a/contracts/eosio.wrap/include/eosio.wrap/eosio.wrap.hpp +++ b/contracts/eosio.wrap/include/eosio.wrap/eosio.wrap.hpp @@ -6,10 +6,8 @@ namespace eosio { /** - * The `eosio.wrap` system contract allows block producers to bypass authorization checks or run privileged actions with 15/21 producer approval and thus simplifies block producers superuser actions. It also makes these actions easier to audit. - * + * \details The `eosio.wrap` system contract allows block producers to bypass authorization checks or run privileged actions with 15/21 producer approval and thus simplifies block producers superuser actions. It also makes these actions easier to audit. * It does not give block producers any additional powers or privileges that do not already exist within the EOSIO based blockchains. As it is implemented, in an EOSIO based blockchain, 15/21 block producers can change an account's permissions or modify an account's contract code if they decided it is beneficial for the blockchain and community. However, the current method is opaque and leaves undesirable side effects on specific system accounts, and thus the `eosio.wrap `contract solves this matter by providing an easier method of executing important governance actions. - * * The only action implemented by the `eosio.wrap` system contract is the `exec` action. This action allows for execution of a transaction, which is passed to the `exec` method in the form of a packed transaction in json format via the 'trx' parameter and the `executer` account that executes the transaction. The same `executer` account will also be used to pay the RAM and CPU fees needed to execute the transaction. */ class [[eosio::contract("eosio.wrap")]] wrap : public contract { @@ -17,24 +15,15 @@ namespace eosio { using contract::contract; /** - * Execute action. - * - * @details Execute a transaction while bypassing regular authorization checks. - * - * Preconditions: - * - Requires authorization of eosio.wrap which needs to be a privileged account. - * - * Postconditions: - * - Deferred transaction RAM usage is billed to 'executer' - * - * @param executer - account executing the transaction, - * @param trx - the transaction to be executed. - * - * @pre + * \details Execute a transaction while bypassing regular authorization checks. + * \preconditions Requires authorization of eosio.wrap which needs to be a privileged account. + * \effects Deferred transaction RAM usage is billed to 'executer'. + * + * \param executer The account executing the transaction. + * \param trx The transaction to be executed. */ - [[eosio::action]] - void exec( ignore executer, ignore trx ); + [[eosio::action]] void exec( ignore executer, ignore trx ); using exec_action = eosio::action_wrapper<"exec"_n, &wrap::exec>; }; -} /// namespace eosio +} diff --git a/contracts/eosio.wrap/src/eosio.wrap.cpp b/contracts/eosio.wrap/src/eosio.wrap.cpp index 12056bf1e..5022265e1 100644 --- a/contracts/eosio.wrap/src/eosio.wrap.cpp +++ b/contracts/eosio.wrap/src/eosio.wrap.cpp @@ -13,4 +13,4 @@ void wrap::exec( ignore, ignore ) { send_deferred( (uint128_t(executer.value) << 64) | (uint64_t)current_time_point().time_since_epoch().count(), executer, _ds.pos(), _ds.remaining() ); } -} /// namespace eosio +} diff --git a/gen-standardese.sh b/gen-standardese.sh new file mode 100755 index 000000000..d66fbcc44 --- /dev/null +++ b/gen-standardese.sh @@ -0,0 +1,10 @@ +#!/bin/bash + +rm -rf ./standardese_generated +docker build -t eosio-contracts-standardese -f ./standardese.dockerfile . +docker create --name eosio-contracts-standardese-temp eosio-contracts-standardese +docker cp eosio-contracts-standardese-temp:/root/eosio-contracts/docs/standardese_generated . +docker rm eosio-contracts-standardese-temp +ls -al ./standardese_generated +pwd + diff --git a/standardese b/standardese new file mode 100755 index 000000000..b4034c61b --- /dev/null +++ b/standardese @@ -0,0 +1,48 @@ +#!/bin/bash + +CDT_DIR=/usr/local/eosio.cdt/eosio.cdt +CDT_SRC_DIR=/root/eosio.cdt +CONTRACTS_SRC_DIR=/root/eosio-contracts + +mkdir -p docs/standardese_generated +pushd docs/standardese_generated +pwd + +pushd $CONTRACTS_SRC_DIR/contracts/eosio.system/include +pwd +ls -al . +popd + +standardese \ + --output.format commonmark \ + --compilation.standard=c++17 \ + --input.blacklist_file type_traits \ + --input.blacklist_file fpconv.c \ + --input.blacklist_file fpconv.h \ + --input.blacklist_file fpconv.license \ + --input.blacklist_file powers.h \ + --input.blacklist_ext .md \ + --input.blacklist_ext .txt \ + --input.blacklist_ext .png \ + --input.blacklist_ext .svg \ + --input.blacklist_ext .in \ + -DGENERATING_DOC \ + -DLLP64 \ + -DEOSIO_NATIVE \ + -I $CDT_DIR/include/eosiolib/core/ \ + -I $CDT_DIR/include/ \ + -I $CDT_DIR/include/libc/ \ + -I $CDT_DIR/include/libcxx/ \ + -I $CDT_SRC_DIR/libraries/eosiolib/contracts \ + -I $CONTRACTS_SRC_DIR/contracts/eosio.bios/include \ + -I $CONTRACTS_SRC_DIR/contracts/eosio.wrap/include \ + -I $CONTRACTS_SRC_DIR/contracts/eosio.msig/include \ + -I $CONTRACTS_SRC_DIR/contracts/eosio.token/include \ + -I $CONTRACTS_SRC_DIR/contracts/eosio.system/include \ + ../../contracts/eosio.bios \ + ../../contracts/eosio.wrap \ + ../../contracts/eosio.msig \ + ../../contracts/eosio.token \ + ../../contracts/eosio.system + +popd diff --git a/standardese.dockerfile b/standardese.dockerfile new file mode 100644 index 000000000..6956164b9 --- /dev/null +++ b/standardese.dockerfile @@ -0,0 +1,74 @@ +from ubuntu:18.04 + +workdir /root +run apt-get update && apt-get install -y wget gnupg +run wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add - + +run echo '\n\ +deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic main\n\ +deb-src http://apt.llvm.org/bionic/ llvm-toolchain-bionic main\n\ +deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic-8 main\n\ +deb-src http://apt.llvm.org/bionic/ llvm-toolchain-bionic-8 main\n' >>/etc/apt/sources.list + +run apt-get update && apt-get install -y \ + autoconf2.13 \ + build-essential \ + bzip2 \ + cargo \ + clang-8 \ + cmake \ + git \ + libboost-all-dev \ + libgmp-dev \ + libpq-dev \ + lld-8 \ + lldb-8 \ + ninja-build \ + nodejs \ + npm \ + pkg-config \ + postgresql-server-dev-all \ + python2.7-dev \ + python3-dev \ + rustc \ + zlib1g-dev + +run update-alternatives --install /usr/bin/clang clang /usr/bin/clang-8 100 +run update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-8 100 + +workdir /root +run git clone https://github.com/EOSIO/eosio.cdt.git +workdir /root/eosio.cdt +run git checkout v1.6.2 +run git submodule update --init --recursive +run mkdir build +workdir /root/eosio.cdt/build +run cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH=/usr/local/eosio.cdt +run ninja +run ninja install + +# Hack in headers that standardese needs +run cp -a /root/eosio.cdt/eosio_llvm/tools/clang/include/clang* /root/eosio.cdt/eosio_llvm/include + +# standardese +workdir /root +run git clone https://github.com/foonathan/standardese.git +workdir /root/standardese +run git checkout 296b92ee52f0a03b6a9b5f52dbee2decaef4a545 +run mkdir /root/standardese/build +workdir /root/standardese/build +run cmake -GNinja -DSTANDARDESE_BUILD_TEST=off -DLLVM_CONFIG_BINARY=/root/eosio.cdt/build/eosio_llvm/bin/llvm-config -DCMAKE_BUILD_TYPE=Debug .. +run ninja +run cp -a tool/standardese /usr/local/bin + +# generate docs +workdir /root +run mkdir -p /root/eosio-contracts/src +copy docs /root/eosio-contracts/docs +copy standardese /root/eosio-contracts +copy contracts /root/eosio-contracts/contracts +workdir /root/eosio-contracts +run bash standardese + +# result is in /root/eosio-contracts/docs/standardese_generated +run ls -al /root/eosio-contracts/docs/standardese_generated diff --git a/standardese.md b/standardese.md new file mode 100644 index 000000000..1d7053494 --- /dev/null +++ b/standardese.md @@ -0,0 +1,12 @@ +# Building the documentation + +``` +rm -rf standardese_generated +docker build -t eosio-contracts-standardese -f ./standardese.dockerfile . +docker create --name eosio-contracts-standardese-temp eosio-contracts-standardese +docker cp eosio-contracts-standardese-temp:/root/eosio-contracts/docs/standardese_generated . +docker rm eosio-contracts-standardese-temp +ls -al ./standardese_generated +``` + +The built documentation is at `/root/eosio-contracts/docs/standardese_generated` inside the image. This copies it to the local `standardese_generated` directory.