Merge pull request #1089 from EOSIO/docs/1.8.x-how-tos_new-template

[docs] 1.8.x - updates to match newest how to template

docs/06_how-to-guides/10_compile/01_compile-a-contract-via-cli.md

@@ -1,20 +1,48 @@
 ---
-content_title: How to compile a contract via CLI
+content_title: How to compile a smart contract via CLI
 ---
 
-## Preconditions
-- You have the source of your contract saved in one of your local folders, e.g. `./examples/hello`
-For details on how to create your first contract follow [this tutorial here](https://developers.eos.io/eosio-home/docs/your-first-contract)
-
-Follow these steps to compile your contract:
-
-1. Navigate to the hello folder in examples (./examples/hello), you should then see the ./src/hello.cpp file
-2. Now run following commands:
-```sh
-$ mkdir build
-$ cd build
-$ eosio-cpp -abigen ../src/hello.cpp -o hello.wasm -I ../include/
-```
-3. This will generate two files:
-- The compiled binary wasm, hello.wasm
-- The generated ABI file, hello.abi
+## Overview
+
+This guide provides instructions how to compile a smart contract using the command line interface (CLI).
+
+## Reference
+
+See the following code reference:
+
+* The [`eosio-cpp`](https://developers.eos.io/manuals/eosio.cdt/latest/command-reference/eosio-cpp) tool.
+
+## Before you begin
+
+* You have the source of the contract saved in a local folder, e.g. `./examples/hello/`
+For details on how to create your first contract follow the [Hello World Contract](https://developers.eos.io/welcome/latest/smart-contract-guides/hello-world) guide.
+
+## Procedure
+
+Follow the following steps to compile your contract.
+
+1. Navigate to the hello folder in examples `./examples/hello`. You should see the `./src/hello.cpp` file.
+
+2. Run the following commands:
+
+    ```sh
+    mkdir build
+    cd build
+    eosio-cpp -abigen ../src/hello.cpp -o hello.wasm -I ../include/
+    ```
+
+    Where:
+    - `eosio-cpp` = Is the [`eosio-cpp`](https://developers.eos.io/manuals/eosio.cdt/latest/command-reference/eosio-cpp) tool.
+    - `-abigen` = It instructs the `eosio-cpp` tool to generate ABI file.
+    - `../src/hello.cpp` = Is the input cpp source file to be compiled.
+    - `-o hello.wasm` = It instructs the `eosio-cpp` tool who to name the output wasm file.
+    - `-I ../include/` = It tells `eosio-cpp` tool what the include folder path is, in this particular case it is relative path.
+
+3. Verify the following two files were generated:
+
+* the compiled binary wasm: `hello.wasm`,
+* and the generated ABI file: `hello.abi`.
+
+## Summary
+
+In conclusion, the above instructions show how to compile a smart contract using the command line interface (CLI).

docs/06_how-to-guides/10_compile/02_how-to-configure-cmake.md

@@ -2,53 +2,77 @@
 content_title: How to configure CMake
 ---
 
-## CMake Configuration
+## Overview
+
+This guide provides instructions how to configure CMake.
+
+## Before you begin
+
+* You have installed CMake, for detailed instructions consult the official [CMake installation page](https://CMake.org/install/).
+
+## Procedure
+
+The following steps show:
+
+* [Automatic generation of CMake configuration](#automatic-generation-of-CMake-configuration)
+* [Manual generation of CMake configuration](#manual-generation-of-CMake-configuration)
 
 ### Automatic generation of CMake configuration
 
-To compile an EOSIO smart contract with CMake, you'll need a CMake file. To use the new `eosio-init` tool to generate the directory structure stub .hpp/.cpp files and the cmake configuration files follow these steps:
+To compile an EOSIO smart contract with CMake, you'll need a CMake file. To use the new `eosio-init` tool to generate the directory structure stub `.hpp/.cpp` files and the CMake configuration files follow these steps:
 
-1. cd ~
-2. eosio-init --path=. --project=test_contract
-3. cd test_contract
-4. cd build
-5. cmake ..
-6. make
-7. ls -al test_contract
+   ```sh
+   cd ~
+   eosio-init --path=. --project=test_contract
+   cd test_contract
+   cd build
+   cmake ..
+   make
+   ls -al test_contract
+   ```
 
 At this point, you'll have the `test_contract.abi` and `test_contract.wasm` files in `~/test_contract/test_contract`. These files are ready to be deployed.
 
 ### Manual generation of CMake configuration
 
-To create manually the cmake configuration, the template `CMakeLists.txt` in the examples folder is a good boilerplate for manual usage.
+To create manually the CMake configuration, the template `CMakeLists.txt` in the examples folder is a good boilerplate for manual usage.
 
 1. In `CMakeLists.txt`:
-```
-cmake_minimum_required(VERSION 3.5)
-project(test_example VERSION 1.0.0)
 
-find_package(eosio.cdt)
+   ```sh
+   cmake_minimum_required(VERSION 3.5)
+   project(test_example VERSION 1.0.0)
+
+   find_package(eosio.cdt)
 
-add_contract( test test test.cpp )
-```
+   add_contract( test test test.cpp )
+   ```
 
 2. In `test.cpp`:
-```
-#include <eosio/eosio.hpp>
-using namespace eosio;
 
-class [[eosio::contract]] test : public eosio::contract {
-public:
-   using contract::contract;
+   ```c++
+   #include <eosio/eosio.hpp>
+   using namespace eosio;
 
-   [[eosio::action]] void testact( name test ) {
-   }
-};
+   class [[eosio::contract]] test : public eosio::contract {
+   public:
+      using contract::contract;
 
-EOSIO_DISPATCH( test, (testact) )
-```
+      [[eosio::action]] void testact( name test ) {
+      }
+   };
+
+   EOSIO_DISPATCH( test, (testact) )
+   ```
 
 3. The following CMake macros are provided:
-- `add_contract` is used to build your smart contract and generate an ABI. The first parameter is the contract name, the second is the cmake target name, and the rest are the CPP files needed to build the contract.
-- `target_ricardian_directory` can be used to add the directory where your ricardian contracts live to a specific cmake target.
-- `add_native_library` and `add_native_executable` are CMake macros for the native tester. They are drop in replacements for `add_library` and `add_executable`.
+
+* `add_contract` is used to build your smart contract and generate an ABI. The first parameter is the contract name, the second is the CMake target name, and the rest are the CPP files needed to build the contract.
+
+* `target_ricardian_directory` can be used to add the directory where your ricardian contracts live to a specific CMake target.
+
+* `add_native_library` and `add_native_executable` are CMake macros for the native tester. They are drop in replacements for `add_library` and `add_executable`.
+
+## Summary
+
+In conclusion, the above instructions show how to configure CMake .

docs/06_how-to-guides/10_compile/03_compiling-contracts-with-cmake.md

@@ -2,20 +2,34 @@
 content_title: How to compile a smart contract with CMake
 ---
 
-## Preconditions
-- You have the source of your contract saved in one of your local folders, e.g. `./examples/hello`
-For details on how to create your first contract follow [this tutorial here](https://developers.eos.io/eosio-home/docs/your-first-contract)
+## Overview
 
-Follow these steps to compile your contract:
+This guide provides instructions on how to compile a smart contract with CMake.
+
+## Before you begin
+
+* You have the source of the contract saved in a local folder, e.g. `./examples/hello/`
+For details on how to create your first contract follow the [Hello World Contract](https://developers.eos.io/welcome/latest/smart-contract-guides/hello-world) guide.
+
+## Procedure
+
+Follow the following steps to compile your contract.
 
 1. Navigate to the hello folder in examples (./examples/hello), you should then see the ./src/hello.cpp file
 2. Run following commands:
-```sh
-$ mkdir build
-$ cd build
-$ cmake ..
-$ make
-```
-3. This will generate two files:
-- The compiled binary wasm, hello.wasm
-- The generated ABI file, hello.abi
+
+    ```sh
+    mkdir build
+    cd build
+    cmake ..
+    make
+    ```
+
+3. Verify the following two files were generated:
+
+* the compiled binary wasm: `hello.wasm`,
+* and the generated ABI file: `hello.abi`.
+
+## Summary
+
+In conclusion, the above instructions show how to compile a smart contract with CMake.

docs/06_how-to-guides/20_authorization/how_to_restrict_access_to_an_action_by_user.md

@@ -3,22 +3,35 @@ content_title: How To Perform Authorization Checks
 link_text: How To Perform Authorization Checks
 ---
 
-## Preconditions
+## Overview
 
-The following conditions are assumed:
+This guide provides instructions how to perform authorization checks in a smart contract.
 
-1. You have the sources of a contract with `hi` action defined.
+## Before you begin
+
+1. You have the sources of a contract with a `hi` action defined and implemented.
 2. The `hi` action has defined one input parameter `user` of type `name`.
-3. The `hi` action prints the name of the `user` account.
-4. The `hi` action needs to authorize the `user` account.
 
-## Authorization Methods
+## Code Reference
 
-To restrict access to the `hi` action, you can do it in three ways.
+See the following code reference guides for functions which can be used to implement authorization checks in a smart contract:
 
-### 1. Use eosio::check(eosio::has_auth(...)...)
+* function [has_auth(name n)](https://developers.eos.io/manuals/eosio.cdt/v1.8/namespaceeosio#function-has_auth)
+* function [require_auth(name n)](https://developers.eos.io/manuals/eosio.cdt/v1.8/namespaceeosio/#function-require_auth-12)
+* function [require_auth2(capi_name name, capi_name permission)](https://developers.eos.io/manuals/eosio.cdt/v1.8/group__action__c#function-require_auth2)
+* function [check(bool pred, ...)](https://developers.eos.io/manuals/eosio.cdt/v1.8/group__system/#function-check)
 
-The below code enforces the action `hi` to be executed only by the account that is sent as parameter to the action, no matter what permission the account uses to sign the transaction (e.g. owner, active, code).
+## Procedure
+
+The following steps show how to check authorization for `user` account for the `hi` action. There are three ways to accomplish an authorization check in a smart contract action implementation. You can use any of the methods provided below depending on your needs:
+
+* [Use check(...) in combination with has_auth(...)](#1-use-checkhas_auth)
+* [Use require_auth(...)](#2-use-require_auth)
+* [Use require_auth2(...)](#3-use-require_auth2)
+
+### 1. Use check(has_auth(...)...)
+
+The following code example enforces the action `hi` to be executed only by the account that is sent as parameter to the action, no matter what permission the account uses to sign the transaction (e.g. owner, active, code).
 
 [[info | Error message is custom]]
 | Observe that in this case the yielded error message is a custom one and thus it can be used to provide a better experience for the user.
@@ -63,3 +76,7 @@ void hi( name user ) {
 
 [[info | Error message is not custom]]
 | Note that this time, as well as previous method, you can not customize the yielded error message, it will be a generic authorization error message.
+
+## Summary
+
+In conclusion, the above instructions show how to perform authorization checks in a smart contract.

docs/06_how-to-guides/30_key-value-api/kv_map/10_how-to-use-kv-map.md

@@ -3,19 +3,33 @@ content_title: How-To Use Key-Value Map
 link_text: "How-To Use Key-Value Map"
 ---
 
-## Summary
+## Overview
+
+This how-to demonstrates how to define and use a `Key-Value Map` (`kv map`) in a smart contract.
+
+To accomplish this task do the following:
+
+1. Instantiate an object of type `eosio::kv::map`.
+2. Specify the name for the instantiated `eosio::kv::map` object.
+3. Specify the type for the map's key.
+4. Specify the type for the values stored for each key.
+5. The key and the values types can be of any standard type or a user defined type.
+
+## Reference
 
-This how-to procedure demonstrates how to define and use a `Key-Value Map` (`kv map`) in your smart contract.
+See the following code reference:
 
-To accomplish this task use `eosio::kv::map` template class, specify the name for the map object instantiated, the type of the key, and the type for the values stored for each key. The types used for the key and the values can be any standard type, or a user defined type.
+* The [`kv::map`](https://developers.eos.io/manuals/eosio.cdt/v1.8/classeosio_1_1kv_1_1map) class.
 
-## Prerequisites
+## Before you begin
 
-* The EOSIO development environment, for details consult the [Get Started](https://developers.eos.io/welcome/latest/getting-started/development-environment/introduction) Guide.
-* A smart contract named `smrtcontract`.
-* A user defined type named `person`, which defines the data stored in the map.
+Make sure you have the following prerequisites in place:
 
-Refer to the following possible implementation of your starting point.
+* An EOSIO development environment, for details consult the [Get Started Guide](https://developers.eos.io/welcome/latest/getting-started-guide/index)
+* A smart contract named `smrtcontract`
+* A user defined type named `person`, which defines the data stored in the map
+
+Refer to the following reference implementation for your starting point:
 
 `smartcontract.hpp file`
 
@@ -39,7 +53,7 @@ class [[eosio::contract]] smartcontract : public eosio::contract {
 Complete the following steps to define the `my_map_t` type, based on the `eosio::kv::map`, which stores objects of type `person` with unique keys of type `int` and instantiate a map object of type `my_map_t`:
 
 * Define the `my_map_t` type based on `eosio::kv::map`.
-* Specify `"kvmap"_n`, which is an `eosio::name`, as the first parameter, to name for the map object.
+* Specify `"kvmap"_n`, which is an `eosio::name`, as the first parameter, to name the map object.
 * Specify `int` as the second parameter to give the type of the unique keys.
 * Specify `person` as the third parameter to give the type of the values stored in the map with each key.
 * Declare and instantiate, as a private data member, an instance of the type `my_map_t`, and name it `my_map`.
@@ -63,6 +77,10 @@ class [[eosio::contract]] smartcontract : public eosio::contract {
 };
 ```
 
+## Summary
+
+In conclusion, the above instructions show how to define and use a `Key-Value Map` (`kv map`) in a smart contract.
+
 ## Next Steps
 
 The following option is available when you complete the procedure:

docs/06_how-to-guides/30_key-value-api/kv_map/30_how-to-upsert-into-kv-map.md

@@ -3,20 +3,20 @@ content_title: How-To Upsert Into Key-Value Map
 link_text: "How-To Upsert Into Key-Value Map"
 ---
 
-## Summary
+## Overview
 
-This how-to procedure provides instructions to upsert into `Key-Value Map` (`kv map`). Upsert means insert when the item doesn't already exist, and update the item if it already exists in the map.
+This how-to provides instructions to upsert into `Key-Value Map` (`kv map`). Upsert means insert when the item doesn't already exist, and update the item if it already exists in the map.
 
-## Prerequisites
+## Before you begin
 
-Before you begin, complete the following prerequisites:
+Make sure you have the following prerequisites in place:
 
-* An EOSIO development environment, for details consult the [Get Started](https://developers.eos.io/welcome/latest/getting-started/development-environment/introduction) Guide
+* An EOSIO development environment, for details consult the [Get Started Guide](https://developers.eos.io/welcome/latest/getting-started-guide/index)
 * A smart contract named `smrtcontract`
 * A user defined type named `person`, which defines the data stored in the map
-* A `kv map` object, name `my_map`, which stores objects of type `person`, with unique keys of type `int`.
+* A `kv map` object, name `my_map`, which stores objects of type `person`, with unique keys of type `int`
 
-Refer to the following possible implementation of your starting point.
+Refer to the following reference implementation for your starting point:
 
 `smartcontract.hpp file`
 
@@ -49,7 +49,7 @@ Complete the following steps to insert a new `person` object with a given ID, if
 2. Create an instance of the `person` class, named `person_upsert`, based on the input parameters: `account_name`, `first_name` and `last_name`.
 3. Use the `[]` operator defined for the `kv::map` type, and set the newly created `person_upsert` object as the value for the `id` key.
 
-Refer to the following possible implementation to insert a new `person` object, and then update it, in the `kv map`:
+Refer to the following reference implementation to insert a new `person` object, and then update it, in the `kv map`:
 
 `smartcontract.hpp file`
 
@@ -105,6 +105,10 @@ void smartcontract::upsert(
 }
 ```
 
+## Summary
+
+In conclusion, the above instructions show how to upsert into `Key-Value Map` (`kv map`).
+
 ## Next Steps
 
 The following options are available when you complete the procedure: