Unified proto/reflection/classes/static encoding API to always return…

… a writer

README.md

@@ -16,7 +16,7 @@ Features
 --------
 * Lightning fast through [runtime code generation](#performance)
 * Exhaustive [browser support](#compatibility)
-* Managed [TypeScript support](#usage-with-typescript)
+* Managed [TypeScript definitions](#usage-with-typescript)
 * Elaborate [API documentation](#documentation)
 * Convenient [CLI utilities](#command-line)
 * Seamless [browserify integration](#browserify-integration)
@@ -102,17 +102,19 @@ protobuf.load("awesome.proto", function(err, root) {
     // Create a new message
     var message = AwesomeMessage.create({ awesomeField: "AwesomeString" });
 
-    // Encode a message (note that reflection encodes to a writer and we need to call finish)
+    // Encode a message
     var buffer = AwesomeMessage.encode(message).finish();
     // ... do something with buffer
 
-    // Or, encode a plain object (note that reflection encodes to a writer and we need to call finish)
+    // Or, encode a plain object
     var buffer = AwesomeMessage.encode({ awesomeField: "AwesomeString" }).finish();
     // ... do something with buffer
 
     // Decode a buffer
     var message = AwesomeMessage.decode(buffer);
     // ... do something with message
+
+    // If your application uses length-delimited buffers, there is also encodeDelimited and decodeDelimited. 
 });
 ```
 
@@ -154,17 +156,7 @@ protobuf.inherits(AwesomeMessage, root.lookup("awesomepackage.AwesomeMessage") /
 
 var message = new AwesomeMessage({ awesomeField: "AwesomeString" });
 
-// Encode a message (note that classes encode to a buffer directly)
-var buffer = AwesomeMessage.encode(message);
-// ... do something with buffer
-
-// Or, encode a plain object (note that classes encode to a buffer directly)
-var buffer = AwesomeMessage.encode({ awesomeField: "AwesomeString" });
-// ... do something with buffer
-
-// Decode a buffer
-var message = AwesomeMessage.decode(buffer);
-// ... do something with message
+// Continue at "Encode a message" above
 ```
 
 Custom classes are automatically populated with static `encode`, `encodeDelimited`, `decode`, `decodeDelimited` and `verify` methods and reference their reflected type via the `$type` property. Note that there are no methods (just `$type`) on instances by default as method names might conflict with field names.
@@ -358,7 +350,7 @@ $> npm run types
 
 ### Browserify integration
 
-protobuf.js integrates nicely into your browserify build-process. There are a few possible tweaks, though:
+protobuf.js integrates into any browserify build-process. There are a few possible tweaks:
 
 * If performance is a concern or IE8 support is required, you should make sure to exclude the browserified `buffer` module and let protobuf.js do its thing with Uint8Array/Array instead.
 * If you do not need int64 support, you can exclude the `long` module.

cli/targets/proto.js

@@ -93,9 +93,9 @@ function buildRoot(root) {
         } else
             break;
     } while (true);
-    if (pkg.length)
-        out.push("package " + pkg.join(".") + ";", "");
     out.push('syntax = "proto' + syntax + '";');
+    if (pkg.length)
+        out.push("", "package " + pkg.join(".") + ";");
 
     buildOptions(ptr);
     ptr.nestedArray.forEach(build);

google/protobuf/descriptor.proto

@@ -1,7 +1,7 @@
-package google.protobuf;
-
 syntax = "proto2";
 
+package google.protobuf;
+
 message FileDescriptorSet {
 
     repeated FileDescriptorProto file = 1;

runtime.js

@@ -6,18 +6,11 @@
  */
 var runtime = exports;
 
-/**
- * @alias Reader
- */
+/** @alias Reader */
 runtime.Reader = require("./src/reader");
 
-/**
- * @alias Writer
- */
+/** @alias Writer */
 runtime.Writer = require("./src/writer");
 
-/**
- * Runtime utility.
- * @memberof runtime
- */
+/** @alias util */
 runtime.util = require("./src/util/runtime");

src/inherits.js

@@ -61,11 +61,11 @@ function inherits(clazz, type, options) {
              * @function
              * @param {Prototype|Object} message Message to encode
              * @param {Writer} [writer] Writer to use
-             * @returns {Uint8Array} Encoded message
+             * @returns {Writer} Writer
              */
             encode: {
                 value: function encode(message, writer) {
-                    return this.$type.encode(message, writer).finish();
+                    return this.$type.encode(message, writer);
                 }
             },
 
@@ -75,11 +75,11 @@ function inherits(clazz, type, options) {
              * @function
              * @param {Prototype|Object} message Message to encode
              * @param {Writer} [writer] Writer to use
-             * @returns {Uint8Array} Encoded message
+             * @returns {Writer} Writer
              */
             encodeDelimited: {
                 value: function encodeDelimited(message, writer) {
-                    return this.$type.encodeDelimited(message, writer).finish();
+                    return this.$type.encodeDelimited(message, writer);
                 }
             },
 

tests/classes.js

@@ -33,7 +33,7 @@ tape.test("google.protobuf.Any class", function(test) {
 
             test.test("should encode", function(test) {
 
-                buf = Any.encode(any);
+                buf = Any.encode(any).finish();
 
                 test.equal(buf[0]    , 1 << 3 | 2, "a tag with id 1, wire type 2");
                 test.equal(buf[1]    , 9         , "a field length of 9");
@@ -55,7 +55,7 @@ tape.test("google.protobuf.Any class", function(test) {
 
             test.test("should encodeDelimited", function(test) {
 
-                buf = Any.encodeDelimited(any);
+                buf = Any.encodeDelimited(any).finish();
 
                 test.equal(buf[0]    , 13        , "a length of 13");
                 test.equal(buf[1]    , 1 << 3 | 2, "a tag with id 1, wire type 2");