From 1ef5e768bb380efac0ab84d15a98e333dc4257f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jeremy=E4=BD=95=E6=B1=9F=E6=98=8E?= Date: Fri, 29 Sep 2023 21:40:53 +0800 Subject: [PATCH] docs: update some documents (#6) --- Cargo.toml | 4 ++-- README.md | 20 +++++++++++++++----- derives/src/container.rs | 4 ++-- src/descriptor.rs | 5 +++++ src/file_generator.rs | 6 ++++++ 5 files changed, 30 insertions(+), 9 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index f8af73a..6eee282 100644 --- a/Cargo.toml +++ b/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"} diff --git a/README.md b/README.md index 86d12b1..8e9557b 100644 --- a/README.md +++ b/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::(); // 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). diff --git a/derives/src/container.rs b/derives/src/container.rs index b93c924..59ce8ee 100644 --- a/derives/src/container.rs +++ b/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"), } } } diff --git a/src/descriptor.rs b/src/descriptor.rs index 6405d84..8581b0f 100644 --- a/src/descriptor.rs +++ b/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), diff --git a/src/file_generator.rs b/src/file_generator.rs index 15b08bc..09501d2 100644 --- a/src/file_generator.rs +++ b/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(&mut self) { T::_register(&mut self.manager); }