From 3cb6a26bd954ef4cdbcb83524e0923b4ee0fa3b4 Mon Sep 17 00:00:00 2001 From: Geoffry Song Date: Sun, 11 Feb 2024 22:30:24 -0800 Subject: [PATCH] Fixes for README, comments --- README.md | 21 +++++++++++---------- pb-jelly-gen/README.md | 2 +- pb-jelly-gen/src/lib.rs | 8 ++++---- pb-jelly/README.md | 2 +- pb-test/dev_setup-osx.sh | 2 +- 5 files changed, 18 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 99e804c..ef770b8 100644 --- a/README.md +++ b/README.md @@ -27,12 +27,12 @@ Other implementations exist in the Rust ecosystem (e.g. [`prost`](https://github ## Features - Functional "Rust-minded" proto extensions, e.g. `[(rust.box_it)=true]` - Scalable - Generates separate crates per module, with option for crate-per-directory - - Autogenerates `Cargo.toml`, or optionally `Spec.toml` / [bazel](https://bazel.build/) `BUILD` files -- Support for [`Serde`](https://serde.rs/) + - Autogenerates `Cargo.toml` +- Support for [`Serde`](https://serde.rs/) (not compliant with the JSON protobuf specification) - Zero-copy deserialization with [`Bytes`](https://docs.rs/bytes/0.5.6/bytes/) via a proto extension `[(rust.zero_copy)=true]` - Automatically boxes messages if it finds a recursive message definition - Retains comments on proto fields -- Supports `proto2` and `proto3` +- Supports `proto2` and `proto3` syntaxes
@@ -56,10 +56,10 @@ Other implementations exist in the Rust ecosystem (e.g. [`prost`](https://github Multiple crates, multiple languages, my oh my! ### Essential Crates -There are only two crates you'll need if you want to use this with you project `pb-jelly` and `pb-jelly-gen`.
+There are only two crates you'll need: `pb-jelly` and `pb-jelly-gen`.
##### `pb-jelly` -Contains all of the important traits and structs that power our generated code, e.g. `Message` and `Lazy`. Include this as a `dependency`, e.g. +Contains all of the important traits and structs that power our generated code, e.g. `Message` and `Lazy`. Include this as a dependency, e.g. ``` [dependencies] pb-jelly = "0.0.16" @@ -67,7 +67,7 @@ pb-jelly = "0.0.16" ##### `pb-jelly-gen` -A framework for generating Rust structs and implementations for `proto2` and `proto3` files. +A framework for generating Rust structs and implementations for `.proto` files. In order to use pb-jelly, you need to add the pb-jelly-gen/codegen/codegen.py as a plugin to your protoc invocation. We added some code here to handle the protoc invocation if you choose to use it. @@ -90,7 +90,7 @@ with `--rust_out=codegen.py` as a plugin for rust. 2. `python3` - The codegen plugin used with `protoc` is written in Python3. #### To generate with pb-jelly-gen -3. Create an inner (build-step) crate which depends on pb-jelly-gen. [Example](https://github.com/dropbox/pb-jelly/tree/master/examples/examples_gen) +3. Create an inner (build-step) crate which depends on pb-jelly-gen. [Example](https://github.com/dropbox/pb-jelly/tree/main/examples/examples_gen) 4. `cargo run` in the directory of the inner generation crate #### To generate manually with protoc @@ -116,7 +116,7 @@ We mention "scalabilty" as a feature, what does that mean? We take an opinionate
-### The Name +### The Name 🌠 pb-jelly is a shoutout to the jellyfish known for its [highly efficient locomotion](https://en.wikipedia.org/wiki/Jellyfish). This library is capable of highly efficient locomotion of deserialized data. Also a shoutout to ability of the jellyfish @@ -141,7 +141,6 @@ Some of the features here require additional tooling to be useful, which are not - Spec.toml is a stripped down templated Cargo.toml - which you can script convert into Cargo.toml in order to get consistent dependency versions in a multi-crate project. Currently, the script to convert Spec.toml -> Cargo.toml isn't yet available -- Autogenerated BUILD files require additional tooling to convert `BUILD.in-gen-proto~` to a BUILD file Closed structs with public fields - Adding fields to a proto file will lead to compiler errors. This can be a benefit in that it allows the @@ -186,6 +185,7 @@ Service Generation - [@isho](https://github.com/isho) - [@benjaminp](https://github.com/benjaminp) - [@grahamking](https://github.com/grahamking) +- [@cyang1](https://github.com/cyang1) ### Non-Dropbox - [@RSMuthu](https://github.com/RSMuthu) @@ -194,4 +194,5 @@ Service Generation [`rust-protobuf`](https://github.com/stepancheg/rust-protobuf) - Rust implementation of Google protocol buffers
[`prost`](https://github.com/danburkert/prost) - PROST! a Protocol Buffers implementation for the Rust Language
[`quick-protobuf`](https://github.com/tafia/quick-protobuf) - A rust implementation of protobuf parser
-[`serde-protobuf`](https://github.com/dflemstr/serde-protobuf) +[`serde-protobuf`](https://github.com/dflemstr/serde-protobuf)
+[`protokit`](https://github.com/semtexzv/protokit) diff --git a/pb-jelly-gen/README.md b/pb-jelly-gen/README.md index 342fc9b..db227fc 100644 --- a/pb-jelly-gen/README.md +++ b/pb-jelly-gen/README.md @@ -2,7 +2,7 @@ ###### It's working! It's working! - Anakin Skywalker [![Crates.io](https://img.shields.io/crates/v/pb-jelly-gen)](https://crates.io/crates/pb-jelly-gen) [![Documentation](https://docs.rs/pb-jelly-gen/badge.svg)](https://docs.rs/pb-jelly-gen) [![Crates.io](https://img.shields.io/crates/l/pb-jelly-gen)](LICENSE) -This crate provides a tool to generate [`Rust`](https://www.rust-lang.org/) code from `proto2` or `proto3` files. +This crate provides a tool to generate [`Rust`](https://www.rust-lang.org/) code from `.proto` files. ### How To Use diff --git a/pb-jelly-gen/src/lib.rs b/pb-jelly-gen/src/lib.rs index 3ebe3dd..fe81277 100644 --- a/pb-jelly-gen/src/lib.rs +++ b/pb-jelly-gen/src/lib.rs @@ -1,14 +1,14 @@ -//! `pb_gen` generates Rust bindings for `proto2` and `proto3` files. It's intended to be used with [`pb_rs`](https://github.com/dropbox/pb-rs). +//! `pb-jelly-gen` generates Rust bindings for `proto` files. It's intended to be used with [`pb-jelly`](https://github.com/dropbox/pb-jelly). //! //! ## Examples //! Complete examples can be found in the [`examples`](https://github.com/dropbox/pb-jelly/tree/main/examples) crate, -//! or the [`pb-test`](https://github.com/dropbox/pb-jelly/tree/main/pb-test) crate of the [`protobuf_rs`](https://github.com/dropbox/pb-rs) workspace. +//! or the [`pb-test`](https://github.com/dropbox/pb-jelly/tree/main/pb-test) crate of the [`pb-jelly`](https://github.com/dropbox/pb-jelly) workspace. //! //! ## In a nutshell 🥜 -//! You can include `pb_gen` in your Cargo project, by including it as a `[build-dependency]` in your `Cargo.toml` +//! You can include `pb-jelly-gen` in your Cargo project, by including it as a `[build-dependency]` in your `Cargo.toml` //! ```toml //! [build-dependencies] -//! pb-gen = "0.1" +//! pb-jelly-gen = "0.0.16" //! ``` //! //! Then from a [`build.rs`](https://doc.rust-lang.org/cargo/reference/build-scripts.html) script, use either the `GenProtos` builder struct, diff --git a/pb-jelly/README.md b/pb-jelly/README.md index 0463c44..76d9427 100644 --- a/pb-jelly/README.md +++ b/pb-jelly/README.md @@ -3,7 +3,7 @@ [![Crates.io](https://img.shields.io/crates/v/pb-jelly)](https://crates.io/crates/pb-jelly) [![Documentation](https://docs.rs/pb-jelly/badge.svg)](https://docs.rs/pb-jelly) [![Crates.io](https://img.shields.io/crates/l/pb-jelly)](LICENSE) -This crates provides the necessary trait implementations to power code generated with [`pb-jelly-gen`](https://github.com/dropbox/pb-jelly/tree/main/pb-gen). You should +This crates provides the necessary trait implementations to power code generated with [`pb-jelly-gen`](https://github.com/dropbox/pb-jelly/tree/main/pb-jelly-gen). You should include this crate as a dependency in your `Cargo.toml`. diff --git a/pb-test/dev_setup-osx.sh b/pb-test/dev_setup-osx.sh index ebb4925..9d8c548 100755 --- a/pb-test/dev_setup-osx.sh +++ b/pb-test/dev_setup-osx.sh @@ -1,7 +1,7 @@ #!/bin/sh # Welcome Messages -printf "Thanks for your interest in developing on \e[34mpb-rs\e[0m!\n\n" +printf "Thanks for your interest in developing on \e[34mpb-jelly\e[0m!\n\n" printf "This script will run the following commands to install the necessary packages, and generate necessary code, for development\n\n" # Describing the packages we install