docs, refactor: update document in idl.

idl/zh-cn/BlsKey.idl

@@ -7,6 +7,29 @@ BlsKey 对象提供了多种构造方法，可以从不同的密钥格式中加
 此外，BlsKey 对象具有 isPrivate()、toJSON(key = "") 等成员属性，可以用于查询密钥是否为私钥以及导出对象的 JSON 格式表示等操作。
 
 BlsKey 对象提供了一组灵活而又强大的 API，可以方便地管理 BLS 密钥，实现身份验证和数据签名等安全需求。
+
+下面我们以一个简单的示例来演示如何使用 BlsKey 对象进行签名和验签：
+```JavaScript
+var crypto = require('crypto');
+
+// 创建一个私钥
+var privateKey = new crypto.BlsKey({
+  'kty': 'EC',
+  'crv': 'BLS12-381-G1',
+  'x': 'TPk62yDxSISkoSBRPYkpO%tJmm0tZd4tJeLuCKVFv4UmBPfOQ2aDWrCifANam2wj',
+  'd': 'zE-pf24p-l0IT_lMcrX0gStTcsx_k1f7DnJmrN8V7ZU',
+});
+
+// 签名消息
+var message = '这是一条需要签名的消息';
+var signature = privateKey.sign(message);
+
+// 验证签名
+var publicKey = privateKey.publicKey;
+var verify = publicKey.verify(message, signature);
+
+console.log('verification result:', verify);
+```
 */
 interface BlsKey : ECKey
 {

idl/zh-cn/BufferedStream.idl

@@ -12,6 +12,29 @@
  BufferedStream 对象还提供了 write 方法将给定的数据写入流，并在底层流对象处于写入阻塞时，等待其可以接受数据后再进行下一步操作。Flush 方法将文件缓冲区内容写入物理设备。close 方法关闭当前流对象。部分方法的具体实现可以在子类中进行实现。
 
  在使用 BufferedStream 对象时，需要注意不要将其与其他已经在使用的底层流对象混用，否则可能会导致数据重复读取或者读取错误。
+
+ 下面是一个使用 BufferedStream 对象读取文件内容的示例代码：
+  ```JavaScript
+  var fs = require('fs');
+  var io = require('io');
+
+  var filename = "test.txt";
+
+  // 打开文件
+  var file = fs.openFile(filename);
+
+  // 创建 BufferedStream 对象
+  var reader = new io.BufferedStream(file);
+
+  // 读取文件所有的行
+  var lines = reader.readLines();
+
+  for(var i = 0; i < lines.length; i ++)
+      console.log(lines[i]);
+
+  // 关闭文件
+  file.close();
+  ```
  */
 interface BufferedStream : Stream
 {

idl/zh-cn/Cipher.idl

@@ -4,6 +4,37 @@
  ```JavaScript
  var c = new crypto.Cipher(crypto.AES, crypto.ECB, ...);
  ```
+
+  下面以 AES 为例，演示如何使用 Cipher 对象进行加密和解密：
+
+  首先，我们需要获取一个对称加密的 Cipher 对象，如 AES 加密算法：
+```JavaScript
+const crypto = require('crypto');
+const key = crypto.randomBytes(16); // 生成 16 字节的随机数作为 AES 密钥
+const cipher = new crypto.Cipher(crypto.AES, crypto.ECB, key);
+```
+以上代码中，我们通过 ``randomBytes`` 方法生成了 16 字节的随机数，作为 AES 密钥。然后，我们创建了一个 AES 算法的 Cipher 对象，使用 ECB 分组密码工作模式，并使用生成的随机数作为密钥。
+
+接下来，我们使用 Cipher 对象的 ``encrypt`` 方法对明文进行加密：
+```JavaScript
+const plaintext = 'Hello, world!';
+const encrypted = cipher.encrypt(plaintext);
+console.log(encrypted); // 输出加密后的结果
+```
+以上代码中，我们使用 ``encrypt`` 方法对字符串 ``Hello, world!`` 进行加密，并输出加密后的结果。
+
+针对以上代码，需要注意以下几点：
+
+- 在进行加密之前，需要先创建一个对称加密的 Cipher 对象，并设置加密算法、密码和分组密码工作模式等参数。
+- 在调用加密方法后，我们可以得到加密后的数据，这通常是一个 Buffer 对象。需要注意，输出的是二进制数据，需要使用相应的方式打印，例如使用 ``Hex`` 等方式进行转换。
+
+如果要解密该数据，我们同样需要一个 Cipher 对象，也是基于 AES 算法，且使用相同的 key 和分组密码工作模式：
+```JavaScript
+const decipher = new crypto.Cipher(crypto.AES, crypto.ECB, key);
+const decrypted = decipher.decrypt(encrypted);
+console.log(decrypted.toString()); // 输出解密后的结果
+```
+在这里，我们创建了一个新的 Cipher 对象，使用相同的 key 和密码工作模式，并且使用 ``decrypt`` 方法对加密数据进行解密。解密的结果是一个 Buffer 对象，需要转换为字符串才能被正确输出。    
  */
 interface Cipher : object
 {

idl/zh-cn/DbConnection.idl

@@ -1,4 +1,14 @@
-/*! @brief 数据库连接对象，用于建立和维护一个数据库连接会话。*/
+/*! @brief DBConnection 是数据库连接的基类，用于建立和维护一个数据库连接会话。其实现了连接的基本操作，并作为派生类的基础。同时支持开始事务、提交事务、回滚事务等操作。 
+
+DBConnection 的子类包括：Odbc、MySQL、SQLite，通过实例化每个子类，我们可以很方便地访问不同种类的数据库。
+
+DBConnection 不能直接创建，只能通过 db.open 等方法创建，例如：
+
+```js
+var db = require("db");
+var conn = db.open("mysql://root:123456@localhost:3306/test");
+```
+*/
 interface DbConnection : object
 {
     /*! @brief 查询当前连接数据库类型 */

idl/zh-cn/Digest.idl

@@ -1,4 +1,24 @@
-/*! @brief 信息摘要对象 */
+/*! @brief 信息摘要对象 
+
+可以这样使用 Digest 对象:
+
+```
+const crypto = require('crypto');
+// 创建 SHA-512 摘要运算对象
+const digest = crypto.createHash('sha512');
+// 更新数据
+digest.update('hello');
+digest.update('world');
+// 获取二进制结果
+const result = digest.digest();
+console.log(result);
+
+// 生成指定编码的结果
+console.log(result.toString('hex'));
+console.log(result.toString('base64'));
+```
+上述代码中，使用 `crypto.createHash()` 方法创建了一个 SHA-512 摘要运算对象，可以通过 `update()` 方法逐步添加要进行摘要的数据，并通过 `digest()` 方法获取摘要结果。
+*/
 interface Digest : object
 {
     /*! @brief 更新二进制摘要信息

idl/zh-cn/ECKey.idl

@@ -1,4 +1,25 @@
-/*! @brief 椭圆曲线加密算法对象 */
+/*! @brief ECKey 类是在 crypto 模块中实现的，可以使用该类来生成 ECDSA 密钥对、签名和验证消息等
+
+以下是一个例子：
+```javascript
+const crypto = require("crypto");
+
+// 生成密钥对
+const key = crypto.generateKey("secp256k1");
+console.log("Private key:", key.pem());
+console.log("Public key:", key.publicKey.pem());
+
+const message = "Hello, fibjs!";
+// 签名消息
+const sig = key.sign(message);
+console.log("Signature:", sig.hex());
+
+// 验证消息
+const verify = key.verify(message, sig);
+console.log("Verify result:", verify);
+```
+
+在该例子中，我们首先生成了一个 secp256k1 的 ECKey 对象，然后打印了生成的公钥和私钥。接着，我们签名了消息 "Hello, fibjs!" 并打印了签名结果，最后使用同样的密钥对象验证了签名，并打印了验证结果。 */
 interface ECKey : PKey
 {
     /*! @brief 通过 DER 格式的密钥构造 ECKey

idl/zh-cn/Ed25519Key.idl

@@ -1,4 +1,27 @@
-/*! @brief 椭圆曲线加密算法对象 */
+/*! @brief 椭圆曲线加密算法对象 
+
+以下示例演示了 Ed25519Key 的用法：
+
+```JavaScript
+const crypto = require('crypto');
+
+// 生成 Ed25519 密钥对
+const key = crypto.generateKey('ed25519');
+
+// 打印公钥、私钥等信息
+console.log('PrivateKey:', key.pem());
+console.log('PublicKey:', key.publicKey.pem());
+
+// 签名消息
+const message = 'Hello, World!';
+const sig = key.sign(message);
+console.log('Sig:', sig.hex());
+
+// 验证签名
+const verifyResult = key.verify(message, sig);
+console.log('Verify Result:', verifyResult);
+```
+*/
 interface Ed25519Key : ECKey
 {
     /*! @brief 从当前对象转换 X25519 公私钥对，仅支持 Ed25519

idl/zh-cn/Event.idl

@@ -1,7 +1,28 @@
-/*! @brief 事件对象
+/*! @brief Event 模块提供了一个事件对象，用于协同共享数据操作。它允许多个纤程（协程）之间进行同步操作，以实现协作式多任务。事件对象有 wait，pulse 和 clear 三个方法，wait 方法将阻塞当前纤程，直至事件被触发，pulse 方法将唤醒所有等待该事件的纤程，而 clear 方法则将事件标志重置为 false。通过使用 coroutine.Event 模块，开发者可以控制纤程之间的执行顺序和数据共享，实现复杂业务逻辑。
 
-通过一个事件达到对一组纤程进行控制的目的（事件对象的状态为bool类型）
+举个例子，假设我们需要两个纤程间进行数据共享，然而它们执行的顺序是不确定的，你可以通过一个事件对象，控制纤程的执行顺序，保证一个纤程执行之前，触发另一个纤程的事件。
+```JavaScript
+const coroutine = require('coroutine');
 
+var evt = new coroutine.Event();
+
+coroutine.start(function() {
+   console.log('[1] wait for event');
+   evt.wait();
+   console.log('[1] receive event');
+});
+
+coroutine.start(function() {
+   loop:for (var i = 0; i < 10; i++) {
+      console.log('[2] do some work');
+      if (i === 5) {
+         evt.pulse();
+      }
+      coroutine.sleep(1000);
+   }
+});
+```
+在上面的例子中，我们创建了一个事件对象 evt，在纤程1中使用wait方法等待事件触发，而在纤程2中通过pulse方法触发事件，当i等于5的时候，纤程2触发事件，纤程1通过事件监听被唤醒，继续执行。在这个过程中，两个纤程之间没有使用任何的锁或其它同步工具，但是它们在纤程级别上保证了数据的同步。
  */
 interface Event : Lock
 {

idl/zh-cn/EventEmitter.idl

@@ -1,11 +1,40 @@
-/*! @brief 事件触发对象，可用于建立观察者模式，支持事件触发的对象均继承于此，同一事件的同一函数只会产生一次回调
+/*! @brief EventEmitter 是事件触发对象，它可以被用于建立观察者模式，支持事件触发的对象均继承于此
 
- Event 对象可独立创建，以用于组建自定义的事件系统：
- ```JavaScript
- var EventEmitter = require('events');
+当一个事件被触发时，所有与该事件相关联的监听器会以异步方式被调用。它还允许我们创建具有高度可定制性和灵活性的代码。
 
- var e = new EventEmitter();
- ```
+常用函数包括：addListener/on、once、removeListener/off、removeAllListeners 和 emit。
+
+下面是一个示例代码：
+
+```javascript
+var fs = require('fs');
+var EventEmitter = require('events');
+var event = new EventEmitter();
+
+event.on('read_file', function(filename) {
+  fs.readFile(filename, 'utf8', function(err, data) {
+    if (err) {
+      event.emit('error', err);
+      return;
+    }
+    event.emit('show_content', data);
+  });
+});
+
+event.on('error', function(err) {
+  console.log(`Error ${err}`);
+});
+
+event.on('show_content', function(content) {
+  console.log(content);
+});
+
+event.emit('read_file', 'test.txt');
+```
+
+上述示例代码，当运行时，事件emitter实例event首先监听'read_file'事件，然后在事件触发时(`event.emit('read_file', 'test.txt')`)触发读取文件的操作。当读取成功后，会触发'show_content'事件，此时监听了'show_content'事件的函数就会被执行并显示文件内容。如果在读取文件过程中发生错误，则会触发'error'事件，此时操作失败的情况就得到了应对。
+
+这种模式在应对异步操作的业务场景中具有很好的优越性。
  */
 interface EventEmitter : object
 {

idl/zh-cn/HttpClient.idl

@@ -1,13 +1,41 @@
-/*! @brief http客户端对象
-
- http客户端对象模拟浏览器环境缓存cookie，并在访问url的时候携带对应的cookie，不同的http客户端对象是相互隔离的，提供http的request、get、post等方法。
- 用法如下：
-
- ```JavaScript
- var http = require('http');
- var httpClient = new http.Client();
- httpClient.request('GET', 'http://fibjs.org');
- ```
+/*! @brief HttpClient 是针对 HTTP 客户端功能设计的类库，提供了基本的 HTTP/HTTPS 请求、代理访问、cookie 管理等功能
+
+使用 HttpClient 可以轻松地访问和操作 web 页面，这里举一个简单的例子——在一个 web 页面上打印出其源代码：
+
+```JavaScript
+const http = require('http');
+
+const res = http.get('http://www.example.com/');
+
+console.log(res.body.readAll().toString());
+```
+
+在该例子中，通过 require 引入 http 模块，然后使用 http.get 发起一个 get 请求，其中 url 参数指定了请求的网址。因为 http.get 方法返回的是一个 HttpResponse 对象，所以可以通过其 body 属性来访问请求返回的主体内容并通过 toString 方法将其转化为字符串。
+
+当请求的 url 是 https 类型而不是 http 类型时，代码只需要将 http 改为 https 即可：
+
+```JavaScript
+const http = require('http');
+
+const res = http.get('https://www.example.com/');
+
+console.log(res.body.readAll().toString());
+```
+
+除此之外，还有通过 HttpClient 直接发起 POST 请求、设置 User-Agent 的例子：
+
+```JavaScript
+const http = require('http');
+
+const httpClient = new http.Client();
+httpClient.userAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36';
+const res = httpClient.post('http://www.example.com/post', {
+    json: { name: 'fibjs', version: '0.31.0' }
+});
+console.log(res.body.readAll().toString());
+```
+
+在该例子中，首先创建了一个 HttpClient 对象 httpClient，并设置其 userAgent 为浏览器的 User-Agent。然后通过它的 post 方法来发起一个 post 请求，其中参数 name 和 version 来指定请求的主体内容。最后将返回值的主体内容输出。
  */
 interface HttpClient : object
 {

idl/zh-cn/HttpCollection.idl

@@ -1,4 +1,55 @@
-/*! @brief http 容器对象，用于 http header，cookie，query，form，等数据的存储与组织 */
+/*! @brief HttpCollection 是一个通用容器，用于处理 http 消息中的 headers, query, form, cookie 数据
+
+我们以 headers 为例，说明 HttpCollection 的使用方法。
+
+HttpCollection 支持三种形式添加数据：
+
+1. 添加一个键值数据，添加数据并不修改已存在的键值的数据。`add`
+
+```JavaScript
+headers.add({
+    'Content-Type': 'text/plain',
+    'User-Agent': 'fibjs'
+});
+```
+
+2. 添加一个键值的一组数据，添加数据并不修改已存在的键值的数据。`add`
+
+```JavaScript
+headers.add('Set-Cookie', [
+    'a=10',
+    'b=20'
+]);
+```
+
+3. 添加一个键值数据，添加数据并不修改已存在的键值的数据。`add`
+
+```JavaScript
+headers.add('Accept-Encoding', 'gzip');
+```
+
+HttpCollection 设置数据的形式与添加相同，使用的方法是 `set`。
+
+我们可以使用 `has` 检查容器内是否存在指定键值的数据
+
+```JavaScript
+const contentTypeExists = headers.has('Content-Type');
+```
+
+使用 `first` 获取容器内某个键对应的第一个值：
+
+```JavaScript
+const contentType = headers.first('Content-Type');
+```
+
+使用 `all` 查询指定键值的全部值，返回一个数组。如果传递一个空字符串的参数，则返回全部值
+
+```JavaScript
+const cookieArray = headers.all('Set-Cookie');
+const alls = headers.all();
+```
+
+使用 `delete` 方法删除指定键值的所有数据，返回 `true` 表示 */
 interface HttpCollection : object
 {
     /*! @brief 清除容器数据 */