Merge pull request #287 from tonlabs/1.3.0-rc

Version 1.3.0

CHANGELOG.md

@@ -1,6 +1,14 @@
 # Release Notes
 All notable changes to this project will be documented in this file.
 
+## 1.3.0 Dec 8, 2020
+
+### Featured
+- `net.query` method . Performs custom graphql query that can be copied directly from the playground. 
+- `net.suspend` and `net.resume` methods for disabling and enabling network activity. One of the possible use-cases is to manage subscriptions when a mobile application is brought to the background and into the foreground again.
+- Smart summary and description doc separation.
+- ts-generator includes doc comments in JSDoc format.
+
 ## 1.2.0 Nov 26, 2020
 
 ### Featured

README.md

@@ -6,7 +6,8 @@
 
 **Documentation**  
 
-[GraphQL API and SDK documentation](https://docs.ton.dev/86757ecb2/p/92b041-overview)
+[API Reference](https://github.com/tonlabs/TON-SDK/blob/master/docs/modules.md)  
+[GraphQL API documentation](https://docs.ton.dev/86757ecb2/p/70a850-introduction)
 
 # What is TONOS Client Library
 
@@ -21,19 +22,18 @@ We ended up with very slow work of pure JavaScript and decided to move all this
 library and link it to Javascript as a compiled binary including a wasm module for browser 
 applications. 
 
-Also this approach provides an opportunity to easily create bindings for any programming 
+Also this approach provided an opportunity to easily create bindings for any programming 
 language and platform, thus, to make it possible to develop distributed applications (DApps) 
 for any possible use-cases, such as: mobile DApps, web DApps, server-side DApps, enterprise 
 DApp etc.
 
 Client Library exposes all the functionality through a few of exported functions. All 
 interaction with library is performed using JSON-RPC like protocol.
 
-Library works over GraphQL API of [TON OS DApp Server](https://github.com/tonlabs/TON-OS-DApp-Server). 
+Library works over [GraphQL API](https://docs.ton.dev/86757ecb2/p/70a850-introduction) of [TON OS DApp Server](https://github.com/tonlabs/TON-OS-DApp-Server). 
 So, it can be used to interact directly with TON OS Clouds: 
 - [Freeton](https://main.ton.dev/graphql)
 - [Devnet](https://net.ton.dev/graphql)
-- [Testnet](https://testnet.ton.dev/graphql)
 
 # How to use library
 

api/derive/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "api_derive"
-version = "1.2.0"
+version = "1.3.0"
 authors = ["Michael Vlasov <[email protected]>"]
 edition = "2018"
 

api/derive/src/utils.rs

@@ -295,6 +295,80 @@ fn generic_type_from(
     }
 }
 
+fn replace_tabs(s: &str) -> String {
+    s.split("\t").collect::<Vec<&str>>().join("    ").trim_end().into()
+}
+
+fn get_leading_spaces(s: &str) -> usize {
+    let mut count = 0;
+    while count < s.len() && &s[count..=count] == " " {
+        count += 1;
+    }
+    count
+}
+
+fn reduce_lines(lines: Vec<String>) -> Vec<String> {
+    if lines.is_empty() {
+        return lines;
+    }
+    let mut min_leading_spaces = None;
+    let mut reduced = Vec::new();
+    for line in &lines {
+        let line = replace_tabs(&line);
+        if !line.is_empty() {
+            let leading_spaces = get_leading_spaces(&line);
+            if min_leading_spaces.is_none() || leading_spaces < min_leading_spaces.unwrap() {
+                min_leading_spaces = Some(leading_spaces);
+            }
+        }
+        reduced.push(line);
+    }
+    if min_leading_spaces.is_some() && min_leading_spaces.unwrap() > 0 {
+        for line in &mut reduced {
+            if !line.is_empty() {
+                *line = line[min_leading_spaces.unwrap()..].into();
+            }
+        }
+    }
+    reduced
+}
+
+
+fn get_doc(element_summary: String, element_description: String) -> (String, String) {
+    if element_description.trim().is_empty() {
+        return (element_summary, String::new());
+    }
+    let lines = reduce_lines(element_description.split("\n").map(|s| s.into()).collect());
+    let mut summary = String::new();
+    let mut summary_complete = false;
+    let mut description = String::new();
+    for line in &lines {
+        if summary_complete {
+            if !line.is_empty() || !description.is_empty() {
+                description.push_str(line);
+                description.push_str("\n");
+            }
+        } else if !line.is_empty() {
+            if !summary.is_empty() {
+                summary.push_str(" ");
+            }
+            if let Some(dot_pos) = line.find(". ").or(line.find(".\n")) {
+                summary.push_str(&line[0..(dot_pos + 1)]);
+                summary_complete = true;
+                description.push_str(&line[(dot_pos + 1)..].trim_start());
+            } else {
+                summary.push_str(line);
+            }
+        } else {
+            if !summary.is_empty() {
+                summary_complete = true;
+            }
+        }
+    }
+    (summary, description.trim().into())
+}
+
+
 pub(crate) fn doc_from(attrs: &Vec<Attribute>) -> (Option<String>, Option<String>) {
     let mut summary = String::new();
     let mut description = String::new();
@@ -326,6 +400,7 @@ pub(crate) fn doc_from(attrs: &Vec<Attribute>) -> (Option<String>, Option<String
             Some(s)
         }
     }
+    let (summary, description) = get_doc(summary, description);
     (non_empty(summary), non_empty(description))
 }
 

api/info/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "api_info"
-version = "1.2.0"
+version = "1.3.0"
 authors = ["Michael Vlasov <[email protected]>"]
 edition = "2018"
 

api/test/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "api_test"
-version = "1.2.0"
+version = "1.3.0"
 authors = ["Michael Vlasov <[email protected]>"]
 edition = "2018"
 

docs/mod_abi.md

@@ -1,7 +1,6 @@
 # Module abi
 
- Provides message encoding and decoding according to the ABI
- specification.
+null
 ## Functions
 [encode_message_body](#encode_message_body) – Encodes message body according to ABI function call.
 
@@ -109,8 +108,8 @@ function encode_message_body(
 ### Result
 
 - `body`: _string_ – Message body BOC encoded with `base64`.
-- `data_to_sign`?: _string_ – Optional data to sign. Encoded with `base64`.
-<br>Presents when `message` is unsigned. Can be used for external<br>message signing. Is this case you need to sing this data and<br>produce signed message using `abi.attach_signature`.
+- `data_to_sign`?: _string_ – Optional data to sign.
+<br>Encoded with `base64`.<br>Presents when `message` is unsigned. Can be used for external<br>message signing. Is this case you need to sing this data and<br>produce signed message using `abi.attach_signature`.
 
 
 ## attach_signature_to_message_body
@@ -133,9 +132,12 @@ function attach_signature_to_message_body(
 ```
 ### Parameters
 - `abi`: _[Abi](mod_abi.md#Abi)_ – Contract ABI
-- `public_key`: _string_ – Public key. Must be encoded with `hex`.
-- `message`: _string_ – Unsigned message body BOC. Must be encoded with `base64`.
-- `signature`: _string_ – Signature. Must be encoded with `hex`.
+- `public_key`: _string_ – Public key.
+<br>Must be encoded with `hex`.
+- `message`: _string_ – Unsigned message body BOC.
+<br>Must be encoded with `base64`.
+- `signature`: _string_ – Signature.
+<br>Must be encoded with `hex`.
 ### Result
 
 - `body`: _string_
@@ -406,8 +408,10 @@ type FunctionHeader = {
 };
 ```
 - `expire`?: _number_ – Message expiration time in seconds. If not specified - calculated automatically from message_expiration_timeout(), try_index and message_expiration_timeout_grow_factor() (if ABI includes `expire` header).
-- `time`?: _bigint_ – Message creation time in milliseconds. If not specified, `now` is used (if ABI includes `time` header).
-- `pubkey`?: _string_ – Public key is used by the contract to check the signature. Encoded in `hex`. If not specified, method fails with exception (if ABI includes `pubkey` header)..
+- `time`?: _bigint_ – Message creation time in milliseconds.
+<br>If not specified, `now` is used(if ABI includes `time` header).
+- `pubkey`?: _string_ – Public key is used by the contract to check the signature.
+<br>Encoded in `hex`.If not specified, method fails with exception (if ABI includes `pubkey` header)..
 
 
 ## CallSet
@@ -433,7 +437,8 @@ type DeploySet = {
 };
 ```
 - `tvc`: _string_ – Content of TVC file encoded in `base64`.
-- `workchain_id`?: _number_ – Target workchain for destination address. Default is `0`.
+- `workchain_id`?: _number_ – Target workchain for destination address.
+<br>Default is `0`.
 - `initial_data`?: _any_ – List of initial values for contract's public variables.
 
 
@@ -456,7 +461,9 @@ Depends on value of the  `type` field.
 
 When _type_ is _'None'_
 
-No keys are provided. Creates an unsigned message.
+No keys are provided.
+
+Creates an unsigned message.
 
 
 When _type_ is _'External'_
@@ -525,13 +532,18 @@ When _type_ is _'StateInit'_
 State init data.
 
 
-- `code`: _string_ – Code BOC. Encoded in `base64`.
-- `data`: _string_ – Data BOC. Encoded in `base64`.
-- `library`?: _string_ – Library BOC. Encoded in `base64`.
+- `code`: _string_ – Code BOC.
+<br>Encoded in `base64`.
+- `data`: _string_ – Data BOC.
+<br>Encoded in `base64`.
+- `library`?: _string_ – Library BOC.
+<br>Encoded in `base64`.
 
 When _type_ is _'Tvc'_
 
-Content of the TVC file. Encoded in `base64`.
+Content of the TVC file.
+
+Encoded in `base64`.
 
 
 - `tvc`: _string_
@@ -684,8 +696,8 @@ type ResultOfEncodeMessageBody = {
 };
 ```
 - `body`: _string_ – Message body BOC encoded with `base64`.
-- `data_to_sign`?: _string_ – Optional data to sign. Encoded with `base64`.
-<br>Presents when `message` is unsigned. Can be used for external<br>message signing. Is this case you need to sing this data and<br>produce signed message using `abi.attach_signature`.
+- `data_to_sign`?: _string_ – Optional data to sign.
+<br>Encoded with `base64`.<br>Presents when `message` is unsigned. Can be used for external<br>message signing. Is this case you need to sing this data and<br>produce signed message using `abi.attach_signature`.
 
 
 ## ParamsOfAttachSignatureToMessageBody
@@ -698,9 +710,12 @@ type ParamsOfAttachSignatureToMessageBody = {
 };
 ```
 - `abi`: _[Abi](mod_abi.md#Abi)_ – Contract ABI
-- `public_key`: _string_ – Public key. Must be encoded with `hex`.
-- `message`: _string_ – Unsigned message body BOC. Must be encoded with `base64`.
-- `signature`: _string_ – Signature. Must be encoded with `hex`.
+- `public_key`: _string_ – Public key.
+<br>Must be encoded with `hex`.
+- `message`: _string_ – Unsigned message body BOC.
+<br>Must be encoded with `base64`.
+- `signature`: _string_ – Signature.
+<br>Must be encoded with `hex`.
 
 
 ## ResultOfAttachSignatureToMessageBody

docs/mod_boc.md

@@ -1,6 +1,6 @@
 # Module boc
 
- BOC manipulation module.
+null
 ## Functions
 [parse_message](#parse_message) – Parses message boc into a JSON
 

docs/mod_client.md

@@ -1,6 +1,6 @@
 # Module client
 
- Provides information about library.
+null
 ## Functions
 [get_api_reference](#get_api_reference) – Returns Core Library API reference
 
@@ -189,7 +189,8 @@ type BuildInfoDependency = {
     git_commit: string
 };
 ```
-- `name`: _string_ – Dependency name. Usually it is a crate name.
+- `name`: _string_ – Dependency name.
+<br>Usually it is a crate name.
 - `git_commit`: _string_ – Git commit hash of the related repository.
 
 
@@ -200,7 +201,8 @@ type ParamsOfAppRequest = {
     request_data: any
 };
 ```
-- `app_request_id`: _number_ – Request ID. Should be used in `resolve_app_request` call
+- `app_request_id`: _number_ – Request ID.
+<br>Should be used in `resolve_app_request` call
 - `request_data`: _any_ – Request describing data