From 0f4420081aebe3f69c10fb9aee2a26e17d5642bf Mon Sep 17 00:00:00 2001
From: "r.4ntix" <r.4ntix@gmail.com>
Date: Thu, 6 Jul 2023 22:46:10 +0800
Subject: [PATCH] chore: update lib doc

---
 src/lib.rs | 102 +++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 83 insertions(+), 19 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 51a4364..28ab0c1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,36 +1,79 @@
 //! Aliyun OpenAPI POP core SDK for Rust.
 //!
-//! # Notes
+//! ## Notes
 //!
 //! You must know your `AK`(`accessKeyId/accessKeySecret`), and the aliyun product's `endpoint` and `apiVersion`.
 //!
-//! For example, The ECS OpenAPI(https://help.aliyun.com/document_detail/25490.html), the API version is `2014-05-26`.
+//! For example, The [ECS OpenAPI](https://help.aliyun.com/document_detail/25490.html), the API version is `2014-05-26`.
 //!
-//! And the endpoint list can be found at [here](https://help.aliyun.com/document_detail/25489.html), the center endpoint is ecs.aliyuncs.com. Add http protocol `http` or `https`, should be `http://ecs.aliyuncs.com/`.
+//! And the endpoint list can be found at [here](https://help.aliyun.com/document_detail/25489.html), the center endpoint is ecs.aliyuncs.com. Add http protocol `http` or `https`, should be `https://ecs.aliyuncs.com/`.
 //!
-//! # Usage
+//! ## Install
+//!
+//! Run the following Cargo command in your project directory:
+//!
+//! ```shell
+//! cargo add aliyun-openapi-core-rust-sdk
+//! ```
+//!
+//! Or add the following line to your Cargo.toml:
+//!
+//! ```toml
+//! aliyun-openapi-core-rust-sdk = "1.0.0"
+//! ```
+//!
+//! ## Usage
 //!
 //! The RPC style client:
 //!
-//! ```no_run
-//! use aliyun_openapi_core_rust_sdk::client::rpc::RPClient;
+//! ```rust
+//! use std::collections::HashMap;
+//! use std::env;
 //! use std::error::Error;
 //!
+//! use aliyun_openapi_core_rust_sdk::client::rpc::RPClient;
+//! use serde::{Deserialize, Serialize};
+//!
+//! #[derive(Serialize, Deserialize, Debug)]
+//! #[serde(rename_all = "PascalCase")]
+//! struct Region {
+//!     region_id: String,
+//!     region_endpoint: String,
+//!     local_name: String,
+//! }
+//!
+//! #[derive(Serialize, Deserialize, Debug)]
+//! #[serde(rename_all = "PascalCase")]
+//! struct RegionList {
+//!     request_id: String,
+//!     regions: HashMap<String, Vec<Region>>,
+//! }
+//!
 //! #[tokio::main]
 //! async fn main() -> Result<(), Box<dyn Error>> {
 //!     // create rpc style api client.
 //!     let aliyun_openapi_client = RPClient::new(
-//!         "<access_key_id>",
-//!         "<access_key_secret>",
-//!         "<endpoint>",
+//!         env::var("ACCESS_KEY_ID")?,
+//!         env::var("ACCESS_KEY_SECRET")?,
+//!         "https://ecs.aliyuncs.com/",
 //!     );
 //!
-//!     // call `DescribeInstances` with queries.
+//!     // call `DescribeRegions` with empty queries, return `RegionList`
 //!     let response = aliyun_openapi_client
+//!         .clone()
+//!         .version("2014-05-26")
+//!         .get("DescribeRegions")
+//!         .json::<RegionList>()
+//!         .await?;
+//!     println!("DescribeRegions response: {response:#?}");
+//!
+//!     // call `DescribeInstances` with queries, return `String`
+//!     let response = aliyun_openapi_client
+//!         .version("2014-05-26")
 //!         .get("DescribeInstances")
 //!         .query([("RegionId", "cn-hangzhou")])
-//!         .text().await?;
-//!
+//!         .text()
+//!         .await?;
 //!     println!("DescribeInstances response: {response}");
 //!
 //!     Ok(())
@@ -39,13 +82,30 @@
 //!
 //! The ROA style client:
 //!
-//! ```no_run
-//! use aliyun_openapi_core_rust_sdk::client::roa::ROAClient;
-//! use serde_json::json;
+//! ```rust
 //! use std::collections::HashMap;
 //! use std::env;
 //! use std::error::Error;
 //!
+//! use aliyun_openapi_core_rust_sdk::client::roa::ROAClient;
+//! use serde::{Deserialize, Serialize};
+//! use serde_json::json;
+//!
+//! #[derive(Serialize, Deserialize, Debug)]
+//! #[serde(rename_all = "PascalCase")]
+//! struct TranslateData {
+//!     word_count: String,
+//!     translated: String,
+//! }
+//!
+//! #[derive(Serialize, Deserialize, Debug)]
+//! #[serde(rename_all = "PascalCase")]
+//! struct Translate {
+//!     request_id: String,
+//!     data: TranslateData,
+//!     code: String,
+//! }
+//!
 //! #[tokio::main]
 //! async fn main() -> Result<(), Box<dyn Error>> {
 //!     // create roa style api client.
@@ -63,21 +123,22 @@
 //!     params.insert("FormatType", "text");
 //!     params.insert("Scene", "general");
 //!
-//!     // call `Translate` with json params.
+//!     // call `Translate` with json params, return `Translate`
 //!     let response = aliyun_openapi_client
 //!         .version("2018-04-08")
 //!         .post("/api/translate/web/general")
 //!         .header([("Content-Type".to_string(), "application/json".to_string())])?
 //!         .body(json!(params).to_string())?
-//!         .text()
+//!         .json::<Translate>()
 //!         .await?;
 //!
-//!     println!("Translate response: {response}");
+//!     println!("Translate response: {response:#?}");
 //!
 //!     Ok(())
 //! }
 //! ```
-//! # Examples
+//!
+//! ## Examples
 //!
 //! Export AK info to env, then run `cargo run --example <NAME>`:
 //!
@@ -96,6 +157,9 @@
 //!
 //! # vpc example
 //! cargo run --example vpc
+//!
+//! # log service(SLS) example
+//! cargo run --example log_service
 //! ```
 #![allow(deprecated)]