Docs: Restructured README

protobufjs · Apr 4, 2017 · 412407d · 412407d
1 parent bed5142
commit 412407d
Show file tree

Hide file tree

Showing 2 changed files with 177 additions and 194 deletions.
diff --git a/README.md b/README.md
@@ -17,12 +17,24 @@ Contents
 * [Examples](#examples)<br />
   A few examples to get you started.
 
-* [Documentation](#documentation)<br />
-  A list of available documentation resources.
+  * [Using .proto files](#using-proto-files)
+  * [Using JSON descriptors](#using-json-descriptors)
+  * [Using reflection only](#using-reflection-only)
+  * [Using custom classes](#using-custom-classes)
+  * [Using services](#using-services)
+  * [Usage with TypeScript](#usage-with-typescript)
 
 * [Command line](#command-line)<br />
   How to use the command line utility.
 
+  * [pbjs for JavaScript](#pbjs-for-javascript)
+  * [pbts for TypeScript](#pbts-for-typescript)
+  * [Reflection vs. static code](#reflection-vs-static-code)
+  * [Command line API](#command-line-api)
+
+* [Additional documentation](#additional-documentation)<br />
+  A list of available documentation resources.
+
 * [Performance](#performance)<br />
   A few internals and a benchmark on performance.
 
@@ -329,7 +341,7 @@ var root = new Root().define("awesomepackage").add(AwesomeMessage);
 ...
 ```
 
-Detailed information on the reflection structure is available within the [documentation](#documentation).
+Detailed information on the reflection structure is available within the [API documentation](#additional-documentation).
 
 ### Using custom classes
 
@@ -465,7 +477,7 @@ protobuf.load("awesome.proto", function(err, root) {
 });
 ```
 
-**Note:** Dynamically generated runtime message classes cannot be typed, technically, so you must either access its fields using `message["awesomeField"]` notation or you can utilize [typings of its static counterpart](https://github.com/dcodeIO/protobuf.js/tree/master/cli#pbts) for full typings support.
+**Note:** Dynamically generated runtime message classes cannot be typed, technically, so you must either access its fields using `message["awesomeField"]` notation or you can utilize [typings of its static counterpart](#pbts-for-typescript) for full typings support.
 
 If you generated static code to `bundle.js` using the CLI and its type definitions to `bundle.d.ts` instead, then you can just do:
 
@@ -486,25 +498,177 @@ var buffer = AwesomeMessage.encode(message).finish();
 /// <reference path="./node_modules/protobufjs/stub-node.d.ts" />
 ```
 
-Documentation
--------------
+Command line
+------------
+
+**Note** that moving the CLI to [its own package](./cli) is a work in progress. At the moment, it's still part of the main package.
+
+The command line interface (CLI) can be used to translate between file formats and to generate static code as well as TypeScript definitions.
+
+### pbjs for JavaScript
+
+```
+Translates between file formats and generates static code.
+
+  -t, --target     Specifies the target format. Also accepts a path to require a custom target.
+
+                  json          JSON representation
+                  json-module   JSON representation as a module
+                  proto2        Protocol Buffers, Version 2
+                  proto3        Protocol Buffers, Version 3
+                  static        Static code without reflection (non-functional on its own)
+                  static-module Static code without reflection as a module
+
+  -p, --path       Adds a directory to the include path.
+
+  -o, --out        Saves to a file instead of writing to stdout.
+
+  --sparse         Exports only those types referenced from a main file (experimental).
+
+   Module targets only:
+
+  -w, --wrap       Specifies the wrapper to use. Also accepts a path to require a custom wrapper.
+
+                   default   Default wrapper supporting both CommonJS and AMD
+                   commonjs  CommonJS wrapper
+                   amd       AMD wrapper
+                   es6       ES6 wrapper (implies --es6)
+
+  -r, --root       Specifies an alternative protobuf.roots name.
+
+  -l, --lint       Linter configuration. Defaults to protobuf.js-compatible rules:
+
+                   eslint-disable block-scoped-var, no-redeclare, no-control-regex, no-prototype-builtins
+
+  --es6            Enables ES6 syntax (const/let instead of var)
+
+   Proto sources only:
+
+  --keep-case      Keeps field casing instead of converting to camel case.
+
+   Static targets only:
+
+  --no-create      Does not generate create functions used for reflection compatibility.
+  --no-encode      Does not generate encode functions.
+  --no-decode      Does not generate decode functions.
+  --no-verify      Does not generate verify functions.
+  --no-convert     Does not generate convert functions like from/toObject
+  --no-delimited   Does not generate delimited encode/decode functions.
+  --no-beautify    Does not beautify generated code.
+  --no-comments    Does not output any JSDoc comments.
+
+  --force-long     Enfores the use of 'Long' for s-/u-/int64 and s-/fixed64 fields.
+  --force-message  Enfores the use of runtime messages instead of plain objects.
+
+usage: pbjs [options] file1.proto file2.json ...  (or)  other | pbjs [options] -
+```
+
+For production environments it is recommended to bundle all your .proto files to a single .json file, which minimizes the number of network requests and avoids any parser overhead (hint: works with just the **light** library):
+
+```
+$> pbjs -t json file1.proto file2.proto > bundle.json
+```
+
+Now, either include this file in your final bundle:
+
+```js
+var root = protobuf.Root.fromJSON(require("./bundle.json"));
+```
+
+or load it the usual way:
+
+```js
+protobuf.load("bundle.json", function(err, root) {
+    ...
+});
+```
+
+Generated static code, on the other hand, works with just the **minimal** library. For example
+
+```
+$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto
+```
+
+will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`.
+
+**ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code.
+
+
+### pbts for TypeScript
+
+```
+Generates TypeScript definitions from annotated JavaScript files.
+
+  -o, --out       Saves to a file instead of writing to stdout.
+
+  -g, --global    Name of the global object in browser environments, if any.
+
+  --no-comments   Does not output any JSDoc comments.
+
+  Internal flags:
+
+  -n, --name      Wraps everything in a module of the specified name.
+
+  -m, --main      Whether building the main library without any imports.
+
+usage: pbts [options] file1.js file2.js ...  (or)  other | pbts [options] -
+```
+
+Picking up on the example above, the following not just generates static code to a CommonJS module `compiled.js` but also its respective TypeScript definitions to `compiled.d.ts`:
+
+```
+$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto
+$> pbts -o compiled.d.ts compiled.js
+```
+
+Additionally, TypeScript definitions of static modules are compatible with their reflection-based counterparts (i.e. as exported by JSON modules), as long as the following conditions are met:
+
+1. Instead of using `new SomeMessage(...)`, always use `SomeMessage.create(...)` because reflection objects do not provide a constructor.
+2. Types, services and enums must start with an uppercase letter to become available as properties of the reflected types as well (i.e. to be able to use `MyMessage.MyEnum` instead of `root.lookup("MyMessage.MyEnum")`).
+
+For example, the following generates a JSON module `bundle.js` and a `bundle.d.ts`, but no static code:
+
+```
+$> pbjs -t json-module -w commonjs -o bundle.js file1.proto file2.proto
+$> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts -
+```
+
+### Reflection vs. static code
+
+While using .proto files directly requires the full library respectively pure reflection/JSON the light library, pretty much all code but the relatively short descriptors is shared.
+
+Static code, on the other hand, requires just the minimal library, but generates additional, albeit editable, source code without any reflection features.
+
+There is no significant difference performance-wise as the code generated statically is pretty much the same as generated at runtime and both are largely interchangeable as seen in the previous section.
+
+### Command line API
+
+Both utilities can be used programmatically by providing command line arguments and a callback to their respective `main` functions:
+
+```js
+var pbjs = require("protobufjs/cli/pbjs"); // or require("protobufjs/cli").pbjs / .pbts
+
+pbjs.main([ "--target", "json-module", "path/to/myproto.proto" ], function(err, output) {
+    if (err)
+        throw err;
+    // do something with output
+});
+```
+
+Additional documentation
+------------------------
 
 #### Protocol Buffers
 * [Google's Developer Guide](https://developers.google.com/protocol-buffers/docs/overview)
 
 #### protobuf.js
 * [API Documentation](http://dcode.io/protobuf.js)
-* [CLI Documentation](./cli/README.md)
 * [CHANGELOG](https://github.com/dcodeIO/protobuf.js/blob/master/CHANGELOG.md)
 * [Frequently asked questions](https://github.com/dcodeIO/protobuf.js/wiki) on our wiki
 
 #### Community
 * [Questions and answers](http://stackoverflow.com/search?tab=newest&q=protobuf.js) on StackOverflow
 
-Command line
-------------
-Command line usage has moved to the (soon to be decoupled) [CLI package](./cli/README.md)
-
 Performance
 -----------
 The package includes a benchmark that tries to compare performance to native JSON as far as this is possible. On an i7-2600K running node 6.9.1 it yields: