update doc of contract def

WeBankBlockchain · Sep 17, 2020 · 97e67c0 · 97e67c0
1 parent 92821f8
commit 97e67c0
Show file tree

Hide file tree

Showing 4 changed files with 56 additions and 54 deletions.
diff --git a/docs/in_depth/contract_definition.md b/docs/in_depth/contract_definition.md
diff --git a/docs/in_depth/create_contract.md b/docs/in_depth/create_contract.md
@@ -0,0 +1,50 @@
+# 创建合约模块
+
+为开发Liquid合约，您首先需要在代码中使用`use`关键字引入`liquid_lang`模块，`liquid_lang`模块中包含了用于定义合约各个组成部分的属性的实现：
+
+```rust
+use liquid_lang as liquid;
+```
+
+在引入的过程中，我们使用了`as`关键字将`liquid_lang`模块重命名为`liquid`，此后您便可以使用这个较短的名字引用`liquid_lang`模块中提供的所有功能。
+
+Liquid使用Rust语言中的模块语法来创建合约，以`mod`关键字表示。您可以自行决定该模块的名字（在`mod`关键字之后），但是建议按照Rust语言代码风格为该模块取名，以防编译器向您发出抱怨。您需要在为该模块添加`#[liquid::contract(...)]`属性，以向Liquid表明此模块包含了合约的完整定义，从而引导Liquid解析您的合约，其中`...`用于描述合约属性：
+
+```rust
+#[liquid::contract(version = "0.1.0", hash_type = "keccak256")]
+mod hello_world {
+    // ...
+}
+```
+
+Liquid合约有两种属性：
+
+- `version`：`version`用于指定所使用的Liquid版本。在未来，随着Liquid不断迭代，可能会引入不兼容的功能特性，在这种情况下，您所指定的Liquid版本将会影响Liquid解析合约的方式。`version`必须以[语义化版本](https://semver.org/lang/zh-CN/)的格式提供，即版本是以英语句号`.`分割的主版本号、次版本号即及修订号。
+
+- `hash_type`：Liquid在某些场合需要使用到哈希函数（如计算合约方法选择器、参数编码等）。`hash_type`提供了两个选项：`keccak256`及`sm3`，用于在不同的场景下，指定Liquid使用的哈希函数类型。当您的合约需要部署至非国密FISCO BCOS区块链平台时，您需要指定`hash_type`为`keccak256`以启用Keccak-256哈希算法；反之，若您的合约需要部署至国密FISCO BCOS区块链平台，则您需要指定`hash_type`为`sm3`以启用国密SM3哈希算法。`hash_type`属性是可选的，当您没有提供时，Liquid默认将`hash_type`设置为`keccak256`。
+
+```eval_rst
+.. admonition:: 注意
+
+   为保证合约能够正常被部署、调用，请务必确认您在``hash_type``中所指定的哈希函数类型符合合约运行环境的要求。
+```
+
+Rust语言中存在声明模块可见性的语法，主要用于控制当前模块能否被其他模块使用，但对于Liquid合约，这种语法并无意义。为避免Liquid合约的表现与您所预期的模块可见性存在差异，Liquid不允许您为合约模块添加任何可见性声明。例如，下列试图将合约模块声明为公开的代码是非法的：
+
+```rust
+#[liquid::contract(version = "0.1.0", hash_type = "keccak256")]
+pub mod hello_world {
+    // ...
+}
+```
+
+除此之外，定义合约的`mod`必须是内联的，即只能使用`mod m { ... }`的形式定义，而其他方式是非法的：
+
+```rust
+#[liquid::contract(version = "0.1.0", hash_type = "keccak256")]
+mod hello_world;
+```
+
+这种形式要求您必须在同一份源代码文件中提供合约的完整定义，从而保证Liquid能够立即解析您的合约。
+
+合约模块创建完成后，你便可以开始在模块中继续定义合约其他的组成部分，包括[状态变量](./state.html)、[合约方法](./method.html)、[事件](./event.html)及[自定义数据结构](./struct.html)。
diff --git a/docs/quick_start/basic_dev_process.md b/docs/quick_start/basic_dev_process.md
@@ -2,15 +2,15 @@
 
 本节主要介绍Liquid合约的开发生命周期，涵盖合约的创建、测试、构建、部署及调用。
 
-## 创建合约
+## 新建合约项目
 
-当您进入到您的工作目录后，您就可以开始着手创建您的合约了。在命令行中执行以下命令：
+当您进入到您的工作目录后，您就可以开始着手创建您的合约项目了。在命令行中执行以下命令：
 
 ```bash
 cargo liquid new hello_world
 ```
 
-`cargo liquid`是调用命令行工具`cargo-liquid`的另一种记法，这种记法有使得`liquid`看上去像是`cargo`子命令的效果。上述命令将会在当前目录下新建一个名为“hello_world”的项目，您此时应该能够看到当面目录下多出来一个名为“hello_world”的目录：
+`cargo liquid`是调用命令行工具`cargo-liquid`的另一种记法，这种记法使得`liquid`看上去像是`cargo`子命令。上述命令将会在当前目录下新建一个名为“hello_world”的项目，您此时应该能够看到当面目录下多出来一个名为“hello_world”的目录：
 
 ```bash
 cd ./hello_world
@@ -31,9 +31,9 @@ hello_world/
 
 从上往下依次介绍各个文件的作用：
 
-1. `.gitignore`：隐藏文件，用于在告诉Git哪些文件或目录不需要被添加到版本管理中。Liquid会默认将某些项目排除在版本管理之外，如果您不需要使用到Git，可以忽略该文件。
+1. `.gitignore`：隐藏文件，用于在告诉Git哪些文件或目录不需要被添加到版本管理中。Liquid会默认将某些项目（如临时文件等）排除在版本管理之外，如果您不需要使用到Git，可以忽略该文件。
 2. `.liquid\`：隐藏目录，用于实现Liquid的某些内部功能，其中`abi_gen`目录下包含了ABI生成器的实现，该目录下的编译配置及代码逻辑是固定的，您不应当修改该目录下的任何文件，否则可能会造成ABI生成出错。
-3. `Cargo.toml`：项目元信息，主要包括项目信息、外部包依赖、编译配置等，一般而言您无需修改该文件，除非您有特殊得需求等（引用新的第三方包、调整优化等级）。
+3. `Cargo.toml`：项目元信息，主要包括项目信息、外部包依赖、编译配置等，一般而言您无需修改该文件，除非您有特殊的需求（引用新的第三方包、调整优化等级等）。
 4. `lib.rs`：Liquid合约源代码，您可以在此文件中进行Liquid合约的开发。
 
 当执行`cargo liquid new`命令时，Liquid会以我们在第一节中介绍过的HelloWorld合约为模板创建新的项目，因此创建出的`lib.rs`文件中包含了HelloWorld合约的代码实现，以及大量的解释每个程序语句的目的及功能的注释，这是一个能直接编译运行的“最简单”的合约。HelloWorld合约我们学习Liquid的起点，随着学习的深入，我们可以基于它开发出功能更为强大的合约！

diff --git a/index.md b/index.md
@@ -18,5 +18,5 @@ Liquid是一种专用于为区块链底层平台[FISCO BCOS](https://fisco-bcos-
    :caption: 深入学习
 
    docs/in_depth/architecture.md
-   docs/in_depth/contract_definition.md
+   docs/in_depth/create_contract.md
 ```