Improve context in documentation (#307)

This spruces up the documentation a bit by: - expanding on the main README to give more context on what Protobuf is and how they can be used - adds some additional examples - adds additional instructions as well as a description of the packages - adds badges for NPM packages and versions - adds table of contents where appropriate To view the main README: https://github.com/bufbuild/protobuf-es/tree/sayers/improve_context_in_docs
bufbuild · Dec 14, 2022 · 3560afe · 3560afe
1 parent 8ff1547
commit 3560afe
Show file tree

Hide file tree

Showing 17 changed files with 505 additions and 255 deletions.
diff --git a/.github/buf-logo.svg b/.github/buf-logo.svg
diff --git a/README.md b/README.md
@@ -1,58 +1,126 @@
-Protobuf-ES
-===========
+![The Buf logo](./.github/buf-logo.svg)
+
+# Protobuf-ES
+
+[![License](https://img.shields.io/github/license/bufbuild/protobuf-es?color=blue)](./LICENSE) [![NPM Version](https://img.shields.io/npm/v/@bufbuild/protobuf/latest?color=green&label=%40bufbuild%2Fprotobuf)](https://www.npmjs.com/package/@bufbuild/protobuf) [![NPM Version](https://img.shields.io/npm/v/@bufbuild/protoplugin/latest?color=green&label=%40bufbuild%2Fprotoplugin)](https://www.npmjs.com/package/@bufbuild/protoplugin) [![NPM Version](https://img.shields.io/npm/v/@bufbuild/protoc-gen-es/latest?color=green&label=%40bufbuild%2Fprotoc-gen-es)](https://www.npmjs.com/package/@bufbuild/protoc-gen-es) 
 
 A complete implementation of [Protocol Buffers](https://developers.google.com/protocol-buffers) in TypeScript,
-suitable for web browsers and Node.js.
+suitable for web browsers and Node.js, created by [Buf](https://buf.build).
+
+## What are Protocol Buffers?
 
-For example, the following definition:
+In a nutshell, Protocol Buffers have two main functions:
 
-```protobuf
-message Person {
-  string name = 1;
-  int32 id = 2;  // Unique ID number for this person.
-  string email = 3;
+- They are a language for writing schemas for your data.
+- They define a binary format for serializing your data.
+
+These two independent traits functions work together to allow your project and everyone who interacts with it to define messages, fields, and service APIs in the exact same way.   In a practical sense as it relates to **Protobuf-ES**, this means no more disparate JSON types all over the place.  Instead, you define a common schema in a Protobuf file, such as:
+
+```proto
+message User {
+  string first_name = 1;
+  string last_name = 2;
+  bool active = 3;
+  User manager = 4;
+  repeated string locations = 5;
+  map<string, string> projects = 6;
 }
 ```
 
-Is compiled to an ECMAScript class that can be used like this:
+And it is compiled to an ECMAScript class that can be used like this:
 
 ```typescript
-let pete = new Person({
-  name: "pete",
-  id: 123
+let user = new User({
+  firstName: "Homer",
+  lastName: "Simpson",
+  active: true,
+  locations: ["Springfield"],
+  projects: { SPP: "Springfield Power Plant" },
+  manager: {
+    firstName: "Montgomery",
+    lastName: "Burns",
+  },
 });
 
-let bytes = pete.toBinary();
-pete = Person.fromBinary(bytes);
-pete = Person.fromJsonString('{"name": "pete", "id": 123}');
+const bytes = user.toBinary();
+user = User.fromBinary(bytes);
+user = User.fromJsonString('{"firstName": "Homer", "lastName": "Simpson"}');
 ```
 
-To learn more, have a look at a complete [code example](https://github.com/bufbuild/protobuf-es/tree/main/packages/protobuf-example), 
-the documentation for the [generated code](https://github.com/bufbuild/protobuf-es/blob/main/docs/generated_code.md), 
-and the documentation for the [runtime API](https://github.com/bufbuild/protobuf-es/blob/main/docs/runtime_api.md).
+The benefits can extend to any application that interacts with yours as well.  This is because the Protobuf file above can be used to generate types in many languages.  The added bonus is that no one has to write any boilerplate code to make this happen.  [Code generators](https://www.npmjs.com/package/@bufbuild/protoc-gen-es) handle all of this for you.
 
+Protocol Buffers also allow you to serialize this structured data.  So, your application running in the browser can send a `User` object to a backend running an entirely different language, but using the exact same definition.  Using an RPC framework like [Connect-Web](https://github.com/bufbuild/connect-web), your data is serialized into bytes on the wire and then deserialized at its destination using the defined schema.
 
-### TypeScript
+## Quickstart
 
-The generated code is compatible with TypeScript **v4.1.2** or later, with the default compiler settings.
+To get started generating code right away, first make sure you have [Buf](https://docs.buf.build/installation) installed.  If desired, you can also use `protoc`.  
 
+1. Install the code generator and the runtime library:
 
-### Packages
+   ```bash
+   npm install @bufbuild/protobuf @bufbuild/protoc-gen-es
+   ```
+
+2. Create a `buf.gen.yaml` file that looks like this:
+
+   ```yaml
+   # Learn more: https://docs.buf.build/configuration/v1/buf-gen-yaml
+   version: v1
+   plugins:
+      - name: es
+        path: ./node_modules/.bin/protoc-gen-es
+        opt: target=ts
+        out: src/gen
+   ```
+
+3. Download the [example.proto](https://github.com/bufbuild/protobuf-es/blob/main/packages/protobuf-test/extra/example.proto) into a `/proto` directory:
+
+   ```bash
+   mkdir proto
+   curl https://raw.githubusercontent.com/bufbuild/protobuf-es/main/packages/protobuf-test/extra/example.proto > proto/example.proto
+   ```
+
+4. Generate your code:
+
+   ```bash
+   buf generate proto
+   ```
+
+You should now see a generated file at `src/gen/example_pb.ts` that contains a class named `User`.  From here, you can begin to work with your schema.
+
+## Packages
 
-- [@bufbuild/protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es):
-  Provides the code generator plugin `protoc-gen-es` ([source](packages/protoc-gen-es)).   
-  The code it generates depends on `@bufbuild/protobuf`.
 - [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf):
-  The runtime library for the code generator plugin `protoc-gen-es` ([source](packages/protobuf)).
+  Provides the runtime library, containing base types, generated well-known types, and core functionality. ([source code](packages/protobuf)).
+- [@bufbuild/protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es):
+  Provides the code generator plugin `protoc-gen-es`.  The code it generates depends on `@bufbuild/protobuf`. ([source code](packages/protoc-gen-es)).
 - [@bufbuild/protoplugin](https://www.npmjs.com/package/@bufbuild/protoplugin):
-  Helps to create your own code generator plugin ([source](packages/protoplugin)).
+  Helps to create your own code generator plugin.  The code it generates depends on `@bufbuild/protobuf`. ([source code](packages/protoplugin)).
+
+## Documentation
 
-### FAQ
+* [Code example](packages/protobuf-example) - Example code that uses protocol buffers to manage an address book.
+* [Generated Code](docs/generated_code.md) - How to generate, and what code precisely is generated for any given protobuf definition.
+* [Runtime API](docs/runtime_api.md) - A detailed overview of the features provided by the library `@bufbuild/protobuf`.
+* [FAQ](docs/faq.md) - Frequently asked Questions.
+* [Migrating to Protobuf-ES](docs/migrating.md) - Shows the changes you'll need to switch your existing code base.
+* [Writing Plugins](docs/writing_plugins.md) - An overview of the process of writing a plugin using `@bufbuild/protoplugin`.
 
-For a list of frequently asked questions, see our [FAQ documentation](docs/faq.md).
+## Ecosystem
+
+* [connect-web](https://github.com/bufbuild/connect-web):
+  TypeScript clients for web browsers, based on Protobuf-ES.
+* [connect-web-integration](https://github.com/bufbuild/connect-web-integration):
+  Example projects using Connect-Web with various JS frameworks and tooling
+* [Buf Studio](https://studio.buf.build/): Web UI for ad-hoc RPCs
+
+
+## TypeScript
+
+The generated code is compatible with TypeScript **v4.1.2** or later, with the default compiler settings.
 
 
-### Copyright
+## Copyright
 
 The [code to encode and decode varint](packages/protobuf/src/google/varint.ts) is Copyright 2008 Google Inc., licensed 
 under BSD-3-Clause.  

diff --git a/docs/migrating.md b/docs/migrating.md
@@ -5,23 +5,51 @@ The following guides show the changes you'll need to switch your existing code b
 [from `protobuf-javascript`](#from-protobuf-javascript) or [from `protobuf-ts`](#from-protobuf-ts) 
 to Protobuf-ES.
 
+- [Feature Matrix](#feature-matrix)
+- [From protobuf-javascript](#from-protobuf-javascript)
+  - [Generating Code](#generating-code)
+  - [Field Access](#field-access)
+  - [Optional Fields](#optional-fields)
+  - [Well-Known Types](#well-known-types)
+  - [Wrapper Fields](#wrapper-fields)
+  - [Map Fields](#map-fields)
+  - [Repeated Fields](#repeated-fields)
+  - [Oneof Groups](#oneof-groups)
+  - [Message Constructors](#message-constructors)
+  - [Serialization](#serialization)
+  - [Enumerations](#enumerations)
+  - [`toObject()`](#toobject)
+- [From protobuf-ts](#from-protobuf-ts)
+  - [Generating Code](#generating-code-1)
+  - [Well-Known Types](#well-known-types-1)
+  - [Wrapper Fields](#wrapper-fields-1)
+  - [Serialization](#serialization-1)
+  - [Message Constructors](#message-constructors-1)
+  - [Cloning](#cloning)
+  - [Message Type Guards](#message-type-guards)
+  - [Reflection](#reflection)
+  - [Dynamic Messages](#dynamic-messages)
+
+
+# Feature Matrix
+
 | Feature                | Protobuf-ES | protobuf-javascript | protobuf-ts |
 |------------------------|-------------|---------------------|-------------|
-| Initializers           | ✔️          |                     | ✔️️         |
-| Plain properties       | ✔️          |                     | ✔️️         |
-| `instanceof`           | ✔️          | ✔️                  | ️️          |
-| JSON format            | ✔️          |                     | ✔️          |
-| Binary format          | ✔️          | ✔️                  | ✔️          |
-| TypeScript             | ✔️          | ️                   | ✔️          |
-| Standard module system | ✔️          |                     | ✔️          |
-| Tree shaking           | ✔️          | ️                   | ✔️          |
-| Reflection             | ✔️          |                     | ✔️          |
-| Dynamic messages       | ✔️          | ️                   | ✔️          |
-| Wrappers unboxing      | ✔️          |                     |             |
-| Comments               | ✔️          |                     | ✔️          |
-| Deprecation            | ✔️          |                     | ✔️          |
-| proto2 syntax          | ✔️          | ✔️                  |             |
-| proto2 extensions      | ️           | ✔️                  |             |
+| Initializers           | ✅          | ❌                    | ✅         |
+| Plain properties       | ✅          | ❌                    | ✅         |
+| `instanceof`           | ✅          | ✅                  | ️️❌          |
+| JSON format            | ✅          | ❌                    | ✅          |
+| Binary format          | ✅          | ✅                  | ✅          |
+| TypeScript             | ✅          | ️❌                   | ✅          |
+| Standard module system | ✅          | ❌                    | ✅          |
+| Tree shaking           | ✅          | ️❌                   | ✅          |
+| Reflection             | ✅          | ❌                    | ✅          |
+| Dynamic messages       | ✅          | ️❌                   | ✅          |
+| Wrappers unboxing      | ✅          | ❌                    | ❌            |
+| Comments               | ✅          | ❌                    | ✅          |
+| Deprecation            | ✅          | ❌                    | ✅          |
+| proto2 syntax          | ✅          | ✅                  | ❌            |
+| proto2 extensions      | ️❌            | ✅                  | ❌            |
 
 
 # From protobuf-javascript