docs: update hz usage document (#787)

Co-authored-by: copy rogers <[email protected]>

Author: Skyenought

content/en/docs/hertz/getting-started/_index.md

@@ -111,7 +111,18 @@ For more information on how to use hz, please refer to: [hz](https://www.cloudwe
 ### Generate/Complete the Sample Code
 
 1. Create the hertz_demo folder in the current directory and go to that directory.
-2. Generate code `hz new`. If your codes are not placed under `GOPATH`, you need to refer [here](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/usage/) and add `-module` (or `-mod`) flag to name your custom module.
+2. Generating code
+- Use `hz new` directly, if not currently in `GOPATH`, you need to add `-module` or `-mod` flag to specify a custom module name. See [here](https://www.cloudwego.io/docs/hertz/tutorials/toolkit/usage/) for details.
+  - Code generation by specifying an already defined idl file, e.g. `hz new -idl hello.thrift`.
+    ```thrift
+    namespace go hello.world
+
+    service HelloService {
+        string Hello(1: string name); 
+    }
+    ```
+    After execution, a scaffolding of the Hertz project is created in the current directory, with a `ping` interface for testing.
+
 3. Tidy & get dependencies.
 
    ```bash
@@ -148,6 +159,25 @@ If nothing goes wrong, we can see the following output:
 
 You have now successfully launched Hertz Server successfully and completed an API call.
 
+### Updating project code
+
+If you need to make further updates to the project, you should use the `hz update` command, here is an example of adding a `Bye` method.
+
+```thrift
+namespace go hello.world
+
+service HelloService {
+    string Hello(1: string name); 
+    string Bye(1: string name);
+}
+```
+
+At this point, run `hz update` from the project root directory to update the project.
+
+```bash
+hz update -idl hello.thrift
+```
+
 ## More examples
 
 Please refer：[Example code](/docs/hertz/tutorials/example/)

content/en/docs/hertz/tutorials/toolkit/usage-protobuf.md

@@ -29,71 +29,71 @@ description: "hz usage(protobuf)."
       option go_package = "/api";
 
       extend google.protobuf.FieldOptions {
-      optional string raw_body = 50101;
-      optional string query = 50102;
-      optional string header = 50103;
-      optional string cookie = 50104;
-      optional string body = 50105;
-      optional string path = 50106;
-      optional string vd = 50107;
-      optional string form = 50108;
-      optional string js_conv = 50109;
-      optional string file_name = 50110;
-      optional string none = 50111;
-
-      // 50131~50160 used to extend field option by hz
-      optional string form_compatible = 50131;
-      optional string js_conv_compatible = 50132;
-      optional string file_name_compatible = 50133;
-      optional string none_compatible = 50134;
-      // 50135 is reserved to vt_compatible
-      // optional FieldRules vt_compatible = 50135;
-
-      optional string go_tag = 51001;
+          optional string raw_body = 50101;
+          optional string query = 50102;
+          optional string header = 50103;
+          optional string cookie = 50104;
+          optional string body = 50105;
+          optional string path = 50106;
+          optional string vd = 50107;
+          optional string form = 50108;
+          optional string js_conv = 50109;
+          optional string file_name = 50110;
+          optional string none = 50111;
+    
+          // 50131~50160 used to extend field option by hz
+          optional string form_compatible = 50131;
+          optional string js_conv_compatible = 50132;
+          optional string file_name_compatible = 50133;
+          optional string none_compatible = 50134;
+          // 50135 is reserved to vt_compatible
+          // optional FieldRules vt_compatible = 50135;
+    
+          optional string go_tag = 51001;
       }
 
       extend google.protobuf.MethodOptions {
-      optional string get = 50201;
-      optional string post = 50202;
-      optional string put = 50203;
-      optional string delete = 50204;
-      optional string patch = 50205;
-      optional string options = 50206;
-      optional string head = 50207;
-      optional string any = 50208;
-      optional string gen_path = 50301; // The path specified by the user when the client code is generated, with a higher priority than api_version
-      optional string api_version = 50302; // Specify the value of the :version variable in path when the client code is generated
-      optional string tag = 50303; // rpc tag, can be multiple, separated by commas
-      optional string name = 50304; // Name of rpc
-      optional string api_level = 50305; // Interface Level
-      optional string serializer = 50306; // Serialization method
-      optional string param = 50307; // Whether client requests take public parameters
-      optional string baseurl = 50308; // Baseurl used in ttnet routing
-      optional string handler_path = 50309; // handler_path specifies the path to generate the method
-
-      // 50331~50360 used to extend method option by hz
-      optional string handler_path_compatible = 50331; // handler_path specifies the path to generate the method
+          optional string get = 50201;
+          optional string post = 50202;
+          optional string put = 50203;
+          optional string delete = 50204;
+          optional string patch = 50205;
+          optional string options = 50206;
+          optional string head = 50207;
+          optional string any = 50208;
+          optional string gen_path = 50301; // The path specified by the user when the client code is generated, with a higher priority than api_version
+          optional string api_version = 50302; // Specify the value of the :version variable in path when the client code is generated
+          optional string tag = 50303; // rpc tag, can be multiple, separated by commas
+          optional string name = 50304; // Name of rpc
+          optional string api_level = 50305; // Interface Level
+          optional string serializer = 50306; // Serialization method
+          optional string param = 50307; // Whether client requests take public parameters
+          optional string baseurl = 50308; // Baseurl used in ttnet routing
+          optional string handler_path = 50309; // handler_path specifies the path to generate the method
+    
+          // 50331~50360 used to extend method option by hz
+          optional string handler_path_compatible = 50331; // handler_path specifies the path to generate the method
       }
 
       extend google.protobuf.EnumValueOptions {
-      optional int32 http_code = 50401;
+          optional int32 http_code = 50401;
 
       // 50431~50460 used to extend enum option by hz
       }
 
       extend google.protobuf.ServiceOptions {
-      optional string base_domain = 50402;
+          optional string base_domain = 50402;
 
-      // 50731~50760 used to extend service option by hz
-      optional string base_domain_compatible = 50731;
+          // 50731~50760 used to extend service option by hz
+          optional string base_domain_compatible = 50731;
       }
 
       extend google.protobuf.MessageOptions {
-      // optional FieldRules msg_vt = 50111;
-
-      optional string reserve = 50830;
-      // 550831 is reserved to msg_vt_compatible
-      // optional FieldRules msg_vt_compatible = 50831;
+          // optional FieldRules msg_vt = 50111;
+    
+          optional string reserve = 50830;
+          // 550831 is reserved to msg_vt_compatible
+          // optional FieldRules msg_vt_compatible = 50831;
       }
       ```
 
@@ -255,34 +255,37 @@ description: "hz usage(protobuf)."
    ```bash
    hz update -I idl -idl idl/hello/hello.proto
    ```
+**Note**.
+- If the dependency of the IDL is not in the same path as the main IDL, you need to add the `-I` option, which means the path to search for the IDL, equivalent to the `-I` command of protoc.
+- When writing update command, you need to specify not only the IDL file that defines `service`, but also all the dependency files, because protobuf's dependency files will not be updated automatically.
 
-3. As you can see
+  3. As you can see
 
-   Add new method under "biz/handler/hello/hello_service.go";
-   The file "new_service.go" and the corresponding "Method3" method have been added under "biz/handler/hello".
+     Add new method under `biz/handler/hello/hello_service.go`;
+     The file `new_service.go` and the corresponding "Method3" method have been added under `biz/handler/hello`.
 
-   Now let's develop the "Method2" interface:
+     Now let's develop the "Method2" interface:
 
-   ```go
-   // Method2 .
-   // @router /other [POST]
-   func Method2(ctx context.Context, c *app.RequestContext) {
-      var err error
-      var req hello.OtherReq
-      err = c.BindAndValidate(&req)
-      if err != nil {
-         c.String(400, err.Error())
-         return
-      }
+     ```go
+     // Method2 .
+     // @router /other [POST]
+     func Method2(ctx context.Context, c *app.RequestContext) {
+        var err error
+        var req hello.OtherReq
+        err = c.BindAndValidate(&req)
+        if err != nil {
+           c.String(400, err.Error())
+           return
+        }
 
-      resp := new(hello.OtherResp)
+        resp := new(hello.OtherResp)
 
-      // added logic
-      resp.Resp = "Other method: " + req.Other
+        // added logic
+        resp.Resp = "Other method: " + req.Other
 
-      c.JSON(200, resp)
-   }
-   ```
+        c.JSON(200, resp)
+     }
+     ```
 
 4. Compile the project
 

content/en/docs/hertz/tutorials/toolkit/usage-thrift.md

@@ -158,10 +158,13 @@ description: "hz usage(thrift)."
    hz update -idl idl/hello.thrift
    ```
 
+**Note**: 
+1. When writing the update command, you only need to specify the IDL file that defines the `service`. hz will automatically generate all the dependencies for that file.
+
 3. As you can see
 
-   Add new method under "biz/handler/hello/example/hello_service.go"<br>
-   The file "new_service.go" and the corresponding "NewMethod" method have been added under "biz/handler/hello/example"
+   Add new method under `biz/handler/hello/example/hello_service.go`<br>
+   The file `new_service.go` and the corresponding "NewMethod" method have been added under `biz/handler/hello/example`.
 
    Now let's develop the "OtherMethod" interface:
 
@@ -213,4 +216,4 @@ description: "hz usage(thrift)."
 
    If it returns `{"Resp":"Other method: other method"}`, it works.
 
-For more example code, please refer to [code](https://github.com/cloudwego/hertz-examples/tree/main/hz/thrift).
+For more example code, please refer to [code](https://github.com/cloudwego/hertz-examples/tree/main/hz/thrift).

content/en/docs/hertz/tutorials/toolkit/usage.md

@@ -66,3 +66,8 @@ description: "hz basic usage."
    ```
 
    If it returns `{"message":"pong"}`, it works.
+
+### Note
+
+`hz new` is only used to initialize the project, use `hz update` to update the project.
+See [using protobuf](./usage-protobuf.md) and [use thrift](./usage-thrift.md).

content/zh/docs/hertz/getting-started/_index.md

@@ -109,7 +109,19 @@ hz 是 Hertz 框架提供的一个用于生成代码的命令行工具，可以
 ### 生成/编写示例代码
 
 1. 在当前目录下创建 hertz_demo 文件夹，进入该目录中。
-2. 生成代码 `hz new`，若当前不在 `GOPATH`，需要添加 `-module` 或者 `-mod` flag 指定一个自定义的模块名称。详细参考[这里](https://www.cloudwego.io/zh/docs/hertz/tutorials/toolkit/usage/)。
+
+2. 生成代码
+  - 直接使用 `hz new`，若当前不在 `GOPATH`，需要添加 `-module` 或者 `-mod` flag 指定一个自定义的模块名称。详细参考[这里](https://www.cloudwego.io/zh/docs/hertz/tutorials/toolkit/usage/)。
+  - 通过指定已经定义好的 idl 文件进行代码生成，例如 `hz new -idl hello.thrift`。
+    ```thrift
+    namespace go hello.world
+    
+    service HelloService {
+        string Hello(1: string name);
+    }
+    ```
+    执行完毕后, 会在当前目录下生成 Hertz 项目的脚手架, 自带一个 `ping` 接口用于测试。 
+
 3. 整理 & 拉取依赖。
 
    ```bash
@@ -146,6 +158,25 @@ curl http://127.0.0.1:8888/ping
 
 到现在，我们已经成功启动了 Hertz Server，并完成了一次调用。
 
+### 更新项目代码
+
+如果需要对项目进行进一步的更新, 应使用 `hz update` 命令, 这里以添加一个 `Bye` 方法为例。
+
+```thrift
+namespace go hello.world
+
+service HelloService {
+    string Hello(1: string name);
+    string Bye(1: string name);
+}
+```
+
+此时在项目根目录执行 `hz update` 更新项目。
+
+```bash
+hz update -idl hello.thrift
+```
+
 ## 更多示例
 
 参考：[代码示例](/zh/docs/hertz/tutorials/example/)