docs: update some documents (#6)

Cargo.toml

@@ -4,9 +4,9 @@ edition = "2018"
 name = "gents"
 version = "0.4.1"
 license = "MIT"
-description = "generate typescript interfaces from rust code"
+description = "generate Typescript interfaces from Rust code"
 repository = "https://github.com/ImJeremyHe/gents"
-keywords = ["Typescript", "interface", "ts-rs", "Rust"]
+keywords = ["Typescript", "interface", "ts-rs", "Rust", "wasm"]
 
 [dev-dependencies]
 gents_derives = {version = "0.4.0", path = "./derives"}

README.md

@@ -5,6 +5,8 @@
 `gents` is a tool for generating **Typescript** interfaces from **Rust** code.
 We can easily use `serde-json` to communicate between **Rust** and **Typescript**,
 without writing **Typescript** stubs trivially.
+It is helpful when your API changes frequently.
+
 It is designed for [LogiSheets](https://github.com/proclml/LogiSheets) and
 is inspired by [`ts-rs`](https://github.com/Aleph-Alpha/ts-rs). Many thanks to them!
 
@@ -23,12 +25,14 @@ It is not necessary and is even an obstacle when we use other build tools like `
 `gents` acts as a binary to generate **Typescript** files.
 
 - `gents` introduces a concept *Group* that from all the members in
-this group files generated will be placed in the same directory. **Group** is seperate from the others even though they can share some
-dependecies. Therefore, `gents` requires you specify the *file_name* on structs
-or enums and specify the *dir* on group, while `ts-rs` requires specifing the *path* on every item.
+this group files generated will be placed in the same directory. **Group** is seperate from the other group even though they can share some
+dependecies. Therefore, `gents` requires you to specify the *file_name* on structs
+or enums and to specify the *dir* on group, while `ts-rs` requires specifing the *path* on every item.
 
 - `gents` helps you manage the export files. And it gathers all the dependencies automatically.
 
+- `gents` is well support for referencing other crates.
+
 - Code generated by `ts-rs` is not match our coding style.
 
 ## How to use `gents`?
@@ -63,7 +67,10 @@ pub struct Group {
 }
 ```
 
-And then you can write a unit test to generate the files like below:
+`derive(TS)` generates code under `#[cfg(any(test, feature="gents"))]`, which means `gents` does not make any difference until you run it.
+
+If all the structs or enums derived from `TS` are in the same crate,
+we recommend that you can write a simple unit test to generate the files like below:
 
 ```rust
 
@@ -72,15 +79,18 @@ And then you can write a unit test to generate the files like below:
 fn gents() {
     use gents::FileGroup;
     let mut group = FileGroup::new();
+    // You don't need to add Person because it is a dependency of Group and it will be added automatically
     group.add::<Group>();
     // If you need to generate the index.ts file, set true.
     group.gen_files("outdir", false);
 }
 ```
 
-After running the binary, there are 2 files generated in `outdir`:
+After running this test, there are 2 files generated in `outdir`:
 
 - person.ts
 - group.ts
 
 Check more cases and usage in the `tests` folder.
+
+If your `derive(TS)`s are from different crates, then you should need to define a feature called `gents`. Please check the detailed usage in [LogiSheets](https://github.com/proclml/LogiSheets/blob/master/crates/buildtools/src/generate.rs).

derives/src/container.rs

@@ -33,7 +33,7 @@ impl<'a> Container<'a> {
                     let s = get_lit_str(&m.lit).expect("rename_all requires lit str");
                     let t = match s.value().as_str() {
                         "camelCase" => RenameAll::CamelCase,
-                        _ => panic!(""),
+                        _ => panic!("unexpected literal for case converting"),
                     };
                     rename_all = Some(t);
                 }
@@ -79,7 +79,7 @@ impl<'a> Container<'a> {
                     rename,
                 }
             }
-            _ => panic!("Not support the union type"),
+            _ => panic!("gents does not support the union type currently, use struct instead"),
         }
     }
 }

src/descriptor.rs

@@ -5,8 +5,11 @@ use std::{
 
 use crate::utils::remove_ext;
 
+// `TS` trait defines the behavior of your types when generating files.
+// `TS` generates some helper functions for file generator.
 pub trait TS {
     fn _register(manager: &mut DescriptorManager) -> usize;
+    // The name of this Rust type in Typescript.
     fn _ts_name() -> String;
     fn _is_optional() -> bool {
         false
@@ -129,6 +132,8 @@ impl DescriptorManager {
     }
 }
 
+// todo: InterfaceDescriptor and EnumDescriptor are the same now.
+// Remove one of it.
 #[derive(Debug)]
 pub enum Descriptor {
     Interface(InterfaceDescriptor),

src/file_generator.rs

@@ -6,6 +6,10 @@ use crate::utils::remove_ext;
 
 const PREFIX: &'static str = r#"// DO NOT EDIT. CODE GENERATED BY gents."#;
 
+/// Members from a FileGroup will:
+/// - generate the .ts files in the same directory
+/// - share their dependencies
+/// - occur overwriting if some of them share the same file name
 pub struct FileGroup {
     manager: DescriptorManager,
 }
@@ -16,6 +20,8 @@ impl FileGroup {
             manager: DescriptorManager::default(),
         }
     }
+
+    /// Add a TS member into this FileGroup.
     pub fn add<T: TS>(&mut self) {
         T::_register(&mut self.manager);
     }