update Ask (#53)

* update Ask

* updateAsk

* updateask

Co-authored-by: lizhaoyang <lizhaoyang@patract.io>

Author: atenjin

src/ask/ask-cli.md

@@ -1,9 +1,10 @@
 # Ask-cli
 
-当前只提供了简单的 cli 来编译合约。 Ask! 提供了 ask 命令来编译 ask 合约：
+当前只提供了简单的cli来编译合约。 Ask! 提供了`ask`命令来编译Ask合约。
 
 ```sh
 npx ask path/to/as-file
 ```
 
-注意 ask 命令需要使用 yarn 或者 npx 来执行以防止 遇到 AssemblyScript 的依赖重复错误。
+**注意** 您需要使用`yarn`或者`npx`的方式来执行`ask`命令，以防止出现AssemblyScript的依赖重复错误。
+

src/ask/ask-vs-ink.md

@@ -1,21 +1,18 @@
-# ask! vs ink!
+# Ask!和ink!的特性比较
 
-下面简单地列出了 ink! 和 ask! 特性比较：
+下表简单列举了ink! 和Ask! 的特性比较。
 
-Here is a brief comparison of features between ink! and ask!:
-
-|                              | ink!                        | ask!                                  |
-| :--------------------------- | :-------------------------- | :------------------------------------ |
-| Language                     | Rust                        | AssemblyScript                        |
-| Overflow Protection          | Enabled by default          | None                                  |
-| Constructor Functions        | Multiple                    | Multiple                              |
-| Tooling                      | Anything that supports Rust | Anything that supports AssemblyScript |
-| Versioning                   | Semantic                    | Semantic                              |
-| Has Metadata?                | Yes                         | Yes                                   |
-| Multi-File Project           | Planned                     | Yes                                   |
-| Storage Entries              | Variable                    | Variable                              |
-| Supported Types              | Docs                        | Docs                                  |
-| Has Interfaces?              | Yes (Rust Traits)           | Yes                                   |
-| Has Inheritance?             | No                          | Yes                                   |
-| Support unit test?           | Yes                         | No                                    |
-| Support cross-contract calls | Preliminary                 | Handy                                 |
+|                    | ink!                        | Ask!                                  |
+| :----------------- | :-------------------------- | :------------------------------------ |
+| 底层语言           | Rust                        | AssemblyScript                        |
+| 溢出保护           | Enabled by default          | None                                  |
+| 构造函数           | Multiple                    | Multiple                              |
+| 可用工具链         | Anything that supports Rust | Anything that supports AssemblyScript |
+| 版本管理           | Semantic                    | Semantic                              |
+| 是否有metadata     | Yes                         | Yes                                   |
+| 是否支持多文件项目 | Planned                     | Yes                                   |
+| 存储模式           | Variable                    | Variable                              |
+| 是否有interface    | Yes (Rust Traits)           | Yes                                   |
+| 是否支持继承       | No                          | Yes                                   |
+| 是否支持单元测试   | Yes                         | No                                    |
+| 是否支持跨合约调用 | Preliminary                 | Handy                                 |

src/ask/basics.md

@@ -1,26 +1,22 @@
 # 基础
 
-Ask! 提供了 `ask-lang` 包，它包含了合约常用存储类型的实现，智能合约底层原语的封装等。
+Ask! 提供了`ask-lang`包，它包括合约常用存储类型的实现、智能合约底层原语的封装等。
 
-## 存储 Storage
+## 存储 
 
 ### 内置存储类型
 
-Ask! 为 AS 的基本类型和标准库集合提供了支持 Scale 编码和存储的版本，
-包括 bool/i{8, 16, 32, 64, 128}/u{8, 16, 32, 64, 128}/string(String)/Array/Set/Map，
-对应于 Bool/Int{8, 16, 32, 64, 128}/u{8, 16, 32, 64, 128}/ScaleString/ScaleArray/ScaleSet/ScaleMap。
+Ask! 为[AssemblyScript](https://www.assemblyscript.org/) 的基本类型和标准库集合提供了支持Scale编码和存储的版本，包括`bool`/`i{8, 16, 32, 64, 128}`/`u{8, 16, 32, 64, 128}`/`string(String)`/`Array`/`Set`/`Map`，对应于                                                                                                                                                      `Bool`/`Int{8, 16, 32, 64, 128}`/`u{8, 16, 32, 64, 128}`/`ScaleString`/`ScaleArray`/`ScaleSet`/`ScaleMap`。当在合约代码相关位置使用了上述提到的基本类型（但不包括`Array`、`Set`、`Map`等容器类型），Ask!会在编译期自动转换为对应的Scale类型（即自动装箱/拆箱）。
 
-当在合约代码相关位置使用了上述提到的基本类型（但不包括 Array/Set/Map 等容器类型），Ask！会在编译期自动转换为对应的 Scale 类型（即自动装箱/拆箱）。
-
-可以通过`ask-lang`导入：
+您可以通过`ask-lang`导入`Bool`。
 
 ```ts
 import { Bool } from 'ask-lang';
 ```
 
 ### 定义存储类型
 
-Ask! 提供 `@storage` 来装饰类为存储类型:
+Ask!提供 `@storage` 来装饰类为存储类型，存储类型里的字段需要支持[Scale编码](https://github.com/paritytech/parity-scale-codec)。
 
 ```ts
 @storage
@@ -32,11 +28,9 @@ class Storage {
 }
 ```
 
-存储类型里的字段需要支持[`Scale`编码](https://github.com/paritytech/parity-scale-codec)。
-
 ### 初始化存储类型
 
-我们可以在合约初始化构造函数里初始化存储值，合约类必须至少提供一个`@constructor`修饰的初始化函数。下面是一个示例：
+我们可以在合约初始化构造函数里初始化存储值，合约类必须至少提供一个`@constructor`修饰的初始化函数。示例如下。
 
 ```ts
 @contract
@@ -54,23 +48,21 @@ class MyContract {
 }
 ```
 
-注意： 默认构造函数/`@constructor`必须是 public 的，否则会出现编译错误。 合约函数的参数和返回值必须是基本类型或者实现Codec编码的类型。
+**注意**  默认构造函数`@constructor`必须是public的，否则会出现编译错误的提示。 合约函数的参数和返回值必须是基本类型或者实现Codec编码的类型。
 
 ### 读取存储值
 
-从之前的代码里可以看出来，Ask! 的存储和合约是可以分开声明的，我们也建议用户分开声明。合约类里声明的函数是真正对外的合约 API，而存储只是实现细节。
+Ask!的存储和合约是可以分开声明的，也建议您分开声明。合约类里声明的函数是真正对外的合约API，而存储只是实现细节。
 
 ### 修改存储值
 
-Ask! 为`@message`方法提供了`mutates`属性，默认为`true`。当设置为`false`时，该方法会在运行时拒绝修改存储值。
-
-<!-- TODO -->
+Ask!为`@message`方法提供了`mutates`属性，默认为`true`。当设置为`false`时，该方法会在运行时拒绝修改存储值。
 
 ### Events
 
-智能合约可以定义在合约执行期间可以发出的事件，第三方工具可以使用发出事件来查询有关合约执行和状态的信息。Event 的字段必须实现`Codec`接口，它们会作为 event data 被收集起来，而 `@topic` 装饰的字段还会作为事件的索引。
+智能合约可以定义在合约执行期间可以发出的事件，第三方工具可以使用发出事件来查询有关合约执行和状态的信息。Event的字段必须实现`Codec`接口，它们会作为event data被收集起来，而 `@topic` 装饰的字段还会作为事件的索引。
 
-### Example
+#### 使用示例
 
 ```ts
 @event
@@ -96,7 +88,7 @@ class Transfer {
 
 Ask! 提供一些类，它们的方法提供了链提供的能力的API：
 
-- Crypto，提供了加密相关的 API
-- Gas，提供了 Gas 相关的 API
-- AccountId 提供了账户相关的 API
-- Msg 提供了 消息相关的 API
+- Crypto：提供了加密相关的API。
+- Gas：提供了Gas相关的API。
+- AccountId ：提供了账户相关的API。
+- Msg ：提供了 消息相关的API。

src/ask/decorators.md

@@ -1,30 +1,26 @@
 # Ask! 装饰器
 
-Ask! 提供了一组装饰器来实现智能合约，通过传递参数对象来配置装饰器的行为。目前装饰器注意分为两层：类装饰器和字段装饰器，字段装饰器必须正确匹配相应的类装饰器。
+Ask! 提供了一组装饰器来实现智能合约，通过传递参数对象来配置装饰器的行为。装饰器主要分为两层，类装饰器和字段装饰器，字段装饰器必须正确匹配相应的类装饰器。当使用的装饰器不加参数时，可以省略小括号。
 
-当使用的装饰器不加参数时，可以省略小括号`()`。
-
-> 注意：以下的装饰器设计仅适用于当前版本，许多特性还未稳定，可能会在未来变动。
+**注意** 以下的装饰器设计仅适用于当前版本，许多特性还未稳定，可能在未来有所变动。
 
 ## @contract
 
 类装饰器
 
-装饰的类会自动成为智能合约一个实例。其子字段支持 `@constructor` 和 `@message` 装饰器装饰。
-
-一个 `AS` 文件 只能定义一个`@contract` 类。
+装饰的类会自动成为智能合约一个实例。其子字段支持 `@constructor` 和 `@message` 装饰器装饰。一个`AS`文件 只能定义一个`@contract` 类。
 
 ## @constructor
 
 字段装饰器
 
-该装饰器用于 `@contract` 的非静态 `public` 方法，该方法不允许返回值（即返回类型为 `void`）。装饰的方法作为该合约的一个初始化构造方法。一个合约至少需要定义一个`@constructor`方法。
+该装饰器用于`@contract` 的非静态public方法，该方法不允许返回值，即返回类型为`void`。装饰的方法作为该合约的一个初始化构造方法。一个合约至少需要定义一个`@constructor`方法。
 
 `@constructor`方法是在合约实例化时可执行的。合约可以定义多个构造方法，允许合约的用户以多种不同的方式实例化合约。
 
 合约构造方法的配置总是为 `payable = true` 和 `mutates = true`。
 
-Example:
+示例如下。
 
 ```ts
 @contract
@@ -46,12 +42,11 @@ class Flipper {
 
 ## @doc
 
-`@doc` 用于为`metadata.json`生成的信息提供文档。它可以为`@contract`/`@event`/`@message`/`@constructor`声明添加文档注释
+`@doc` 用于为`metadata.json`生成的信息提供文档。它可以为`@contract`/`@event`/`@message`/`@constructor`声明添加文档注释。
 
-Example:
+示例如下。
 
 ```ts
-
 @contract
 @doc(desc = "MyToken conract that implement erc20 contract")
 class MyToken {
@@ -63,16 +58,16 @@ class MyToken {
 
 字段装饰器
 
-该装饰器用于 `@contract` 的 非静态 `public` 方法。装饰的方法作为合约的消息 API 供用户调用该合约。一个合约至少需要定义一个`@constructor`方法或者继承了其他合约。
+该装饰器用于 `@contract`的非静态public方法。装饰的方法作为合约的消息API供用户调用该合约。一个合约至少需要定义一个`@constructor`方法或者继承了其他合约。
 
-`@message`方法是在合约执行的被调用的。合约可以定义多个消息方法。消息方法的返回值会返回给用户，因此需要实现`Codec`接口。如果你需要返回一些集合类型，那么需要使用 ask! 提供的一些实现 `Codec` 接口的集合类型。
+`@message`方法是在合约执行的被调用的。合约可以定义多个消息方法。消息方法的返回值会返回给用户，因此需要实现`Codec`接口。如果您需要返回一些集合类型，那么需要使用Ask! 提供的一些实现 `Codec` 接口的集合类型。
 
 合约消息方法默认配置为`payable = false` 和 `mutates = true`，当配置为`true`时，合约会在运行时做相应的检查。
 
-- `payable` 表明方法可以接受 value
-- `mutates` 表明方法是否能够改变存储变量的值
+- `payable` 表示方法可以接受value。
+- `mutates` 表示方法是否能够改变存储变量的值。
 
-Example:
+示例如下。
 
 ```ts
 @contract
@@ -112,23 +107,21 @@ class Flipper {
 
 类装饰器
 
-详见[Event](./basics.md#Events)
+详情请参见[Event](./basics.md#Events)。
 
 ## @topic
 
 字段装饰器
 
-`@topic` 装饰的属性字段，会额外生成一个主题索引。每个事件的索引是有数量限制的（默认最大为 4 个）。
+`@topic` 装饰的属性字段，会额外生成一个主题索引。每个事件的索引是有数量限制的（默认最大为4个）。
 
 ## @dynamic
 
 类装饰器
 
-`@dynamic` 装饰器用来装饰一个合约的 APIs，这个合约已经存在于链上。通过在`@dynamic`类里声明链上的合约接口，ask 会自动生成相应的跨合约调用代码。
-
-Example:
+`@dynamic` 装饰器用来装饰一个合约的APIs，这个合约已经存在于链上。通过在`@dynamic`类里声明链上的合约接口，Ask会自动生成相应的跨合约调用代码。
 
-假设下面的合约 A 已经存在链上：
+假设下面的合约A已经存在链上。
 
 ```ts
 @contract
@@ -145,7 +138,7 @@ class Libadd {
 }
 ```
 
-我们在合约 B 里面想调用该合约，那么我们可以声明一个`@dynamic`类来描述其接口：
+如果想在合约B里面想调用该合约，您可以声明一个`@dynamic`类来描述其接口。
 
 ```ts
 @dynamic
@@ -172,6 +165,6 @@ class LibaddCaller {
 }
 ```
 
-这里的 outAddress 是合约 Libadd 的实例地址。
+这里的`outAddress`是合约Libadd的实例地址。
 
-该功能也可以调用其他智能合约语言编写的合约，比如 ink!，只要遵循兼容的 metadata.json 规范。
+该功能也可以调用其他智能合约语言编写的合约，例如ink!，只要遵循兼容的metadata.json规范。

src/ask/design.md

@@ -2,25 +2,24 @@
 
 ## Ask! 设计总览
 
-AssemblyScript 使用 asc 编译器将 AssemblyScript 文件编译为 WebAssembly 字节码。 但是无法直接生成符合 `pallet-contract` ABI 的 wasm 字节码和`metadata.json`元信息文件,因此需要编写 AS transform 介入编译器编译流程，在合适的位置生成 ABI 相关的代码并导出，在类型信息确定之后生成 `metadata.json`。
+AssemblyScript使用asc编译器将AssemblyScript文件编译为WebAssembly字节码，但是无法直接生成符合 `pallet-contract` ABI的 Wasm字节码和`metadata.json`元信息文件,因此您需要编写AS transform介入编译器编译流程，在合适的位置生成ABI相关的代码并导出，在类型信息确定之后生成 `metadata.json`。
 
 ## 设计思路
 
-Ask! 提供了 `ask-transform`（在以下描述中简称为 `transform`）和 `ask-lang` 两个库。
-此外，我们在后续将提供一个名为 `ask-cli` 的构建工具（类似于 ink!的`cargo-contract`），用于帮助建立和管理用 Ask！编写的 Wasm 智能合约。
+Ask! 提供了 `ask-transform`（简称 `transform`）和 `ask-lang` 两个库。
+此外，我们在后续将提供一个名为 `ask-cli` 的构建工具，这个工具类似于ink!的`cargo-contract`，用于帮助建立和管理用Ask编写的Wasm智能合约。
 
 Ask! 的功能按照如下实现：
 
-- `ask-lang`的主要功能是为编写智能合约提供高层 API，包括`pallet-contract`原语高层封装/scale 编码/KV 存储抽象/常用的基本类型/通用的 interfaces。用户可以通过装饰器来自动派生这些基本类的组合。
-- `ask-transform`的主要功能是根据 Ask! 代码里使用的装饰器，生成符合`pallet-contract` 规范的代码和`metadata.json`元信息文件文件。这个部分需要完成以下任务：
-
-  - 解析合约接口和参数，并生成元数据文件
-  - 解析自定义合约装饰器，生成相应的逻辑代码
-  - 根据存储的定义按照一定流程读/写合约存储
+- `ask-lang`的主要功能是为编写智能合约提供高层API，包括`pallet-contract`原语高层封装、Scale 编码、K/V存储抽象、常用的基本类型和通用的 interfaces。您可以通过装饰器来自动派生这些基本类的组合。
+- `ask-transform`的主要功能根据Ask! 代码里使用的装饰器，生成符合`pallet-contract` 规范的代码和`metadata.json`元信息文件，这个部分实现以下功能：
+  - 解析合约接口和参数，并生成元数据文件。
+  - 解析自定义合约装饰器，生成相应的逻辑代码。
+  - 根据存储的定义按照一定流程读/写合约存储。
 
 <!-- TODO: 未实现 -->
-<!-- - `ask-cli`的主要功能是在 cli 中管理 Ask!项目，其中包括以下功能：
+<!-- - `ask-cli`的主要功能是在cli中管理Ask!项目，其中包括以下功能：
 
-  - 创建 ask!合约模板。
-  - 使用额外的工具如 wasm-opt 来优化 wasm 代码
-  - 检查所生成的 Wasm 代码的合法性。 -->
+  - 创建Ask!合约模板。
+  - 使用额外的工具例如wasm-opt来优化Wasm代码。
+  - 检查所生成的Wasm代码的合法性。 -->