Docs: Reference Buffer for BufferReader/Writer, see #668

Author: dcodeIO

README.md

@@ -72,14 +72,18 @@ The library supports both reflection-based and code-based use cases:
 
 There is a suitable distribution for each of these:
 
-| Build   | GZ Size | Downloads                    | How to require                  | Description
+|         | Gzipped | Downloads                    | How to require                  | Description
 |---------|---------|------------------------------|---------------------------------|-------------
 | full    | 18.5kb  | [dist][dist-full]            | `require("protobufjs")`         | All features. Works with everything.
 | light   | 15.5kb  | [dist/light][dist-light]     | `require("protobufjs/light")`   | All features except tokenizer, parser and bundled common types. Works with JSON definitions, pure reflection and static code.
 | minimal | 6.0kb+  | [dist/minimal][dist-minimal] | `require("protobufjs/minimal")` | Just enough to run static code. No reflection.
 
 In case of doubt you can just use the full library.
 
+[dist-full]: https://github.com/dcodeIO/protobuf.js/tree/master/dist
+[dist-light]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/light
+[dist-minimal]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/minimal
+
 Examples
 --------
 
@@ -302,7 +306,7 @@ protobuf.load("awesome.proto", function(err, root) {
 });
 ```
 
-To achieve the same with static code generated by [pbjs](https://github.com/dcodeIO/protobuf.js#command-line), there is the [pbts](https://github.com/dcodeIO/protobuf.js#generating-typescript-definitions-from-static-modules) command line utility to generate type definitions from static code as well.
+To achieve the same with static code generated by [pbjs](#command-line), there is the [pbts](#generating-typescript-definitions-from-static-modules) command line utility to generate type definitions from static code as well.
 
 Let's say you generated your static code to `bundle.js` and its type definitions to `bundle.d.ts`, then you can do:
 
@@ -358,13 +362,15 @@ Consolidates imports and converts between file formats.
                   default   Default wrapper supporting both CommonJS and AMD
                   commonjs  CommonJS wrapper
                   amd       AMD wrapper
-                  es6       ES6 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
+                  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:
 
@@ -410,7 +416,7 @@ As you might have noticed, `pbjs` is also capable of generating static code. For
 $> 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`, which then can be used with just the [minimal library][dist-minimal].
+will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`, which then can be used with just the [minimal library](#distributions).
 
 **ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code.
 
@@ -421,16 +427,18 @@ Likewise, the `pbts` command line utility can be used to generate TypeScript def
 ```
 Generates TypeScript definitions from annotated JavaScript files.
 
-  -n, --name      Wraps everything in a module of the specified name.
-
   -o, --out       Saves to a file instead of writing to stdout.
 
-  -m, --main      Whether building the main library without any imports.
-
   -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] -
 ```
 
@@ -455,9 +463,9 @@ $> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts -
 
 ### On reflection vs. static code
 
-While using .proto files directly requires the [full library][dist-full] respectively pure reflection/JSON the [light library][dist-light], pretty much all code but the relatively short descriptors is shared.
+While using .proto files directly requires the [full library](#distributions) respectively pure reflection/JSON the [light library](#distributions), pretty much all code but the relatively short descriptors is shared.
 
-Static code, on the other hand, requires just the [minimal library][dist-minimal], but generates additional, albeit editable, source code without any reflection features.
+Static code, on the other hand, requires just the [minimal library](#distributions), 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.
 
@@ -590,11 +598,17 @@ $> npm run types
 
 By default, protobuf.js integrates into your browserify build-process without requiring any optional modules. Hence:
 
-* If you need int64 support, explicitly require the `long` module somewhere in your project. It will be excluded otherwise.
-* If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) as a reference.
+* If you need int64 support, explicitly require the `long` module somewhere in your project as it will be excluded otherwise. This assumes that a global `require` function is present that protobuf.js can call to obtain the long module.
 
-**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)
+  If there is no global `require` function present after bundling, it's also possible to assign the long module programmatically:
 
-[dist-full]: https://github.com/dcodeIO/protobuf.js/tree/master/dist
-[dist-light]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/light
-[dist-minimal]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/minimal
+  ```js
+  var Long = ...;
+  
+  protobuf.util.Long = Long;
+  protobuf.configure();
+  ```
+
+* If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) for reference.
+
+**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)

cli/pbts.js

@@ -45,16 +45,18 @@ exports.main = function(args, callback) {
                 "",
                 chalk.bold.white("Generates TypeScript definitions from annotated JavaScript files."),
                 "",
-                "  -n, --name      Wraps everything in a module of the specified name.",
-                "",
                 "  -o, --out       Saves to a file instead of writing to stdout.",
                 "",
-                "  -m, --main      Whether building the main library without any imports.",
-                "",
                 "  -g, --global    Name of the global object in browser environments, if any.",
                 "",
                 "  --no-comments   Does not output any JSDoc comments.",
                 "",
+                chalk.bold.gray("  Internal flags:"),
+                "",
+                "  -n, --name      Wraps everything in a module of the specified name.",
+                "",
+                "  -m, --main      Whether building the main library without any imports.",
+                "",
                 "usage: " + chalk.bold.green("pbts") + " [options] file1.js file2.js ..." + chalk.bold.gray("  (or)  ") + "other | " + chalk.bold.green("pbts") + " [options] -"
             ].join("\n"));
         if (callback)

index.d.ts

@@ -1174,10 +1174,10 @@ export class Reader {
     /**
      * Creates a new reader using the specified buffer.
      * @function
-     * @param {Uint8Array} buffer Buffer to read from
-     * @returns {BufferReader|Reader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader}
+     * @param {Uint8Array|Buffer} buffer Buffer to read from
+     * @returns {Reader|BufferReader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader}
      */
-    static create(buffer: Uint8Array): (BufferReader|Reader);
+    static create(buffer: (Uint8Array|Buffer)): (Reader|BufferReader);
 
     /**
      * Reads a varint as an unsigned 32 bit value.
@@ -1314,6 +1314,21 @@ export class BufferReader extends Reader {
      * @param {Buffer} buffer Buffer to read from
      */
     constructor(buffer: Buffer);
+
+    /**
+     * Read buffer.
+     * @name BufferReader#buf
+     * @type {Buffer}
+     */
+    buf: Buffer;
+
+    /**
+     * Reads a sequence of bytes preceeded by its length as a varint.
+     * @name BufferReader#bytes
+     * @function
+     * @returns {Buffer} Value read
+     */
+    bytes(): Buffer;
 }
 
 /**
@@ -2703,9 +2718,24 @@ export class BufferWriter extends Writer {
     /**
      * Allocates a buffer of the specified size.
      * @param {number} size Buffer size
-     * @returns {Uint8Array} Buffer
+     * @returns {Buffer} Buffer
      */
-    static alloc(size: number): Uint8Array;
+    static alloc(size: number): Buffer;
+
+    /**
+     * Writes a sequence of bytes.
+     * @param {Buffer|string} value Buffer or base64 encoded string to write
+     * @returns {Writer} `this`
+     */
+    bytes(value: (Buffer|string)): Writer;
+
+    /**
+     * Finishes the write operation.
+     * @name BufferWriter#finish
+     * @function
+     * @returns {Buffer} Finished buffer
+     */
+    finish(): Buffer;
 }
 
 /**

src/reader.js

@@ -43,8 +43,8 @@ function Reader(buffer) {
 /**
  * Creates a new reader using the specified buffer.
  * @function
- * @param {Uint8Array} buffer Buffer to read from
- * @returns {BufferReader|Reader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader}
+ * @param {Uint8Array|Buffer} buffer Buffer to read from
+ * @returns {Reader|BufferReader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader}
  */
 Reader.create = util.Buffer
     ? function create_buffer_setup(buffer) {

src/reader_buffer.js

@@ -16,6 +16,12 @@ var util = require("./util/minimal");
  */
 function BufferReader(buffer) {
     Reader.call(this, buffer);
+
+    /**
+     * Read buffer.
+     * @name BufferReader#buf
+     * @type {Buffer}
+     */
 }
 
 /* istanbul ignore else */
@@ -29,3 +35,10 @@ BufferReader.prototype.string = function read_string_buffer() {
     var len = this.uint32(); // modifies pos
     return this.buf.utf8Slice(this.pos, this.pos = Math.min(this.pos + len, this.len));
 };
+
+/**
+ * Reads a sequence of bytes preceeded by its length as a varint.
+ * @name BufferReader#bytes
+ * @function
+ * @returns {Buffer} Value read
+ */

src/writer_buffer.js

@@ -22,7 +22,7 @@ function BufferWriter() {
 /**
  * Allocates a buffer of the specified size.
  * @param {number} size Buffer size
- * @returns {Uint8Array} Buffer
+ * @returns {Buffer} Buffer
  */
 BufferWriter.alloc = function alloc_buffer(size) {
     return (BufferWriter.alloc = util._Buffer_allocUnsafe)(size);
@@ -42,7 +42,9 @@ var writeBytesBuffer = Buffer && Buffer.prototype instanceof Uint8Array && Buffe
     };
 
 /**
- * @override
+ * Writes a sequence of bytes.
+ * @param {Buffer|string} value Buffer or base64 encoded string to write
+ * @returns {Writer} `this`
  */
 BufferWriter.prototype.bytes = function write_bytes_buffer(value) {
     if (util.isString(value))
@@ -71,3 +73,11 @@ BufferWriter.prototype.string = function write_string_buffer(value) {
         this.push(writeStringBuffer, len, value);
     return this;
 };
+
+
+/**
+ * Finishes the write operation.
+ * @name BufferWriter#finish
+ * @function
+ * @returns {Buffer} Finished buffer
+ */