Merge pull request #356 from EOSIO/docs/starter

Add eosio.contracts documentation content to release/1.9.x

README.md

@@ -18,19 +18,7 @@ Dependencies:
 * [eosio.cdt v1.7.x](https://github.com/EOSIO/eosio.cdt/releases/tag/v1.7.0-rc1)
 * [eosio v2.0.x](https://github.com/EOSIO/eos/releases/tag/v2.0.0-rc1) (optional dependency only needed to build unit tests)
 
-To build contracts alone:
-1. Ensure an appropriate version of eosio.cdt is installed. Installing eosio.cdt from binaries is sufficient.
-2. Run the `build.sh` script in the top directory to build all the contracts.
-
-To build the contracts and unit tests:
-1. Ensure an appropriate version of eosio.cdt is installed. Installing eosio.cdt from binaries is sufficient.
-2. Ensure an appropriate version of eosio has been built from source and installed. Installing eosio from binaries is not sufficient.
-3. Run the `build.sh` script in the top directory with the `-t` flag to build all the contracts and the unit tests for these contracts.
-
-After build:
-* If the build was configured to also build unit tests, the unit tests executable is placed in the _build/tests_ folder and is named __unit_test__.
-* The contracts (both `.wasm` and `.abi` files) are built into their corresponding _build/contracts/\<contract name\>_ folder.
-* Finally, simply use __cleos__ to _set contract_ by pointing to the previously mentioned directory for the specific contract.
+To build the contracts follow the instructions in [`Build and deploy` section](./docs/02_build-and-deploy.md).
 
 ## Contributing
 

contracts/eosio.bios/include/eosio.bios/eosio.bios.hpp

@@ -36,14 +36,6 @@ namespace eosiobios {
    using eosio::permission_level;
    using eosio::public_key;
 
-   /**
-    * A weighted permission.
-    *
-    * @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. The weight is going to be
-    * used against a threshold, if the weight is equal or greater than the threshold set then authorization
-    * will pass.
-    */
    struct permission_level_weight {
       permission_level  permission;
       uint16_t          weight;
@@ -52,11 +44,6 @@ namespace eosiobios {
       EOSLIB_SERIALIZE( permission_level_weight, (permission)(weight) )
    };
 
-   /**
-    * Weighted key.
-    *
-    * @details A weighted key is defined by a public key and an associated weight.
-    */
    struct key_weight {
       eosio::public_key  key;
       uint16_t           weight;
@@ -65,11 +52,6 @@ namespace eosiobios {
       EOSLIB_SERIALIZE( key_weight, (key)(weight) )
    };
 
-   /**
-    * Wait 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;
       uint16_t           weight;
@@ -78,15 +60,6 @@ namespace eosiobios {
       EOSLIB_SERIALIZE( wait_weight, (wait_sec)(weight) )
    };
 
-   /**
-    * Blockchain authority.
-    *
-    * @details An authority is defined by:
-    * - a vector of key_weights (a key_weight is a public key plus a weight),
-    * - 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)
-    * - a threshold value
-    */
    struct authority {
       uint32_t                              threshold = 0;
       std::vector<key_weight>               keys;
@@ -97,19 +70,6 @@ namespace eosiobios {
       EOSLIB_SERIALIZE( authority, (threshold)(keys)(accounts)(waits) )
    };
 
-   /**
-    * Blockchain block header.
-    *
-    * @details A block header is defined by:
-    * - a timestamp,
-    * - the producer that created it,
-    * - a confirmed flag default as zero,
-    * - a link to previous block,
-    * - a link to the transaction merkel root,
-    * - a link to action root,
-    * - a schedule version,
-    * - and a producers' schedule.
-    */
    struct block_header {
       uint32_t                                  timestamp;
       name                                      producer;
@@ -125,26 +85,9 @@ namespace eosiobios {
                                      (schedule_version)(new_producers))
    };
 
-   /**
-    * @defgroup eosiobios eosio.bios
-    * @ingroup eosiocontracts
-    *
-    * eosio.bios is a minimalistic system contract that only supplies the actions that are absolutely
-    * critical to bootstrap a chain and nothing more.
-    *
-    * @{
-    */
    class [[eosio::contract("eosio.bios")]] bios : public eosio::contract {
       public:
          using contract::contract;
-         /**
-          * @{
-          * These actions map one-on-one with the ones defined in
-          * [Native Action Handlers](@ref native_action_handlers) section.
-          * 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
           *
@@ -358,11 +301,6 @@ namespace eosiobios {
          [[eosio::action]]
          void reqactivated( const eosio::checksum256& feature_digest );
 
-         /**
-          * Abi hash structure
-          *
-          * @details Abi hash structure is defined by contract owner and the contract hash.
-          */
          struct [[eosio::table]] abi_hash {
             name              owner;
             checksum256       hash;
@@ -371,9 +309,6 @@ namespace eosiobios {
             EOSLIB_SERIALIZE( abi_hash, (owner)(hash) )
          };
 
-         /**
-          * Multi index table that stores the contracts' abi index by their owners/accounts.
-          */
          typedef eosio::multi_index< "abihash"_n, abi_hash > abi_hash_table;
 
          using newaccount_action = action_wrapper<"newaccount"_n, &bios::newaccount>;
@@ -392,5 +327,4 @@ namespace eosiobios {
          using activate_action = action_wrapper<"activate"_n, &bios::activate>;
          using reqactivated_action = action_wrapper<"reqactivated"_n, &bios::reqactivated>;
    };
-   /** @}*/ // end of @defgroup eosiobios eosio.bios
-} /// namespace eosiobios
+}

contracts/eosio.msig/include/eosio.msig/eosio.msig.hpp

@@ -6,6 +6,7 @@
 #include <eosio/transaction.hpp>
 
 namespace eosio {
+
    /**
     * @defgroup eosiomsig eosio.msig
     * @ingroup eosiocontracts
@@ -27,8 +28,7 @@ namespace eosio {
           * authorized by the provided keys and permissions, and if the proposal name doesn’t
           * already exist; if all validations pass the `proposal_name` and `trx` trasanction are
           * saved in the proposals table and the `requested` permission levels to the
-          * approvals table (for the `proposer` context).
-          * Storage changes are billed to `proposer`.
+          * 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)
@@ -46,8 +46,7 @@ namespace eosio {
           * 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`.
+          * 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)