Docs: Added extended usage instructions for TypeScript and custom classes to README, see #666

Author: dcodeIO

README.md

@@ -150,11 +150,19 @@ var root = new Root().define("awesomepackage").add(AwesomeMessage);
 ```js
 ...
 
+// define your own prototypical class
 function AwesomeMessage(properties) {
-    protobuf.Message.call(this, properties);
+    protobuf.Message.call(this, properties); // call the super constructor
 }
+
+// register your custom class with its reflected type
 protobuf.Class.create(root.lookup("awesomepackage.AwesomeMessage") /* or use reflection */, AwesomeMessage);
 
+// define your custom functionality
+AwesomeMessage.customStaticMethod = function() { ... };
+AwesomeMessage.prototype.customInstanceMethod = function() { ... };
+
+// create a message
 var message = new AwesomeMessage({ awesomeField: "AwesomeString" });
 
 // Continue at "Encode a message" above
@@ -212,15 +220,42 @@ There is also an [example for streaming RPC](https://github.com/dcodeIO/protobuf
 
 ### Usage with TypeScript
 
+The library ships with its own [type definitions](https://github.com/dcodeIO/protobuf.js/blob/master/index.d.ts) and modern editors like [Visual Studio Code](https://code.visualstudio.com/) should automatically detect and use them for code completion when following this pattern:
+
 ```ts
+// node.js
 import * as protobuf from "protobufjs";
 import * as Long from "long"; // optional
-...
+
+// browser only (alternatively)
+import * as protobuf from "./node_modules/protobufjs/index.js";
+import * as Long from "./node_modules/long/dist/long.js"; // optional
+
+protobuf.load("awesome.proto", function(err, root) {
+  if (err)
+    throw err;
+
+  // example code
+  var AwesomeMessage = root.lookupType("AwesomeMessage");
+  var message = AwesomeMessage.create({ awesomeField: "hello" });
+  var buffer = AwesomeMessage.encode(message).finish();
+  ...
+});
 ```
 
-See also: [Generating your own TypeScript definitions](https://github.com/dcodeIO/protobuf.js#generating-typescript-definitions-from-static-modules)
+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.
+
+Let's say you generated your static code to `bundle.js` and its type definitions to `bundle.d.ts`, then you can do:
+
+```ts
+import * as root from "./bundle.js";
 
-Additional configuration might be necessary when not utilizing node, i.e. reference [protobuf.js.d.ts](https://github.com/dcodeIO/protobuf.js/blob/master/index.d.ts) and [long.js.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/types-2.0/long/index.d.ts).
+// example code
+var AwesomeMessage = root.AwesomeMessage;
+var message = AwesomeMessage.create({ awesomeField: "hello" });
+var buffer = AwesomeMessage.encode(message).finish();
+...
+```
 
 Documentation
 -------------

src/util/minimal.js

@@ -1,27 +1,39 @@
 "use strict";
 var util = exports;
 
-util.asPromise    = require("@protobufjs/aspromise");
-util.base64       = require("@protobufjs/base64");
+// used to return a Promise where callback is omitted
+util.asPromise = require("@protobufjs/aspromise");
+
+// converts to / from base64 encoded strings
+util.base64 = require("@protobufjs/base64");
+
+// base class of rpc.Service
 util.EventEmitter = require("@protobufjs/eventemitter");
-util.inquire      = require("@protobufjs/inquire");
-util.utf8         = require("@protobufjs/utf8");
-util.pool         = require("@protobufjs/pool");
 
-util.LongBits     = require("./longbits");
+// requires modules optionally and hides the call from bundlers
+util.inquire = require("@protobufjs/inquire");
+
+// convert to / from utf8 encoded strings
+util.utf8 = require("@protobufjs/utf8");
+
+// provides a node-like buffer pool in the browser
+util.pool = require("@protobufjs/pool");
+
+// utility to work with the low and high bits of a 64 bit value
+util.LongBits = require("./longbits");
 
 /**
  * An immuable empty array.
  * @memberof util
  * @type {Array.<*>}
  */
-util.emptyArray = Object.freeze ? Object.freeze([]) : /* istanbul ignore next */ [];
+util.emptyArray = Object.freeze ? Object.freeze([]) : /* istanbul ignore next */ []; // used on prototypes
 
 /**
  * An immutable empty object.
  * @type {Object}
  */
-util.emptyObject = Object.freeze ? Object.freeze({}) : /* istanbul ignore next */ {};
+util.emptyObject = Object.freeze ? Object.freeze({}) : /* istanbul ignore next */ {}; // used on prototypes
 
 /**
  * Whether running within node or not.
@@ -73,8 +85,23 @@ util.Buffer = (function() {
     }
 })();
 
-// Aliases where supported, otherwise polyfills
+/**
+ * Internal alias of or polyfull for Buffer.from.
+ * @type {?function}
+ * @param {string|number[]} value Value
+ * @param {string} [encoding] Encoding if value is a string
+ * @returns {Uint8Array}
+ * @private
+ */
 util._Buffer_from = null;
+
+/**
+ * Internal alias of or polyfill for Buffer.allocUnsafe.
+ * @type {?function}
+ * @param {number} size Buffer size
+ * @returns {Uint8Array}
+ * @private
+ */
 util._Buffer_allocUnsafe = null;
 
 /**
@@ -230,7 +257,7 @@ util._configure = function() {
         util._Buffer_from = util._Buffer_allocUnsafe = null;
         return;
     }
-    // node 4.2.0 - 4.4.7 support makes it impossible to just polyfill these.
+    // because node 4.x buffers are incompatible & immutable
     // see: https://github.com/dcodeIO/protobuf.js/pull/665
     util._Buffer_from = Buffer.from !== Uint8Array.from && Buffer.from ||
         /* istanbul ignore next */