Document all the callbacks, see #527

README.md

@@ -331,12 +331,12 @@ Consolidates imports and converts between file formats.
 
   -t, --target    Specifies the target format. Also accepts a path to require a custom target.
 
-                  json-module   JSON representation as a module (AMD, CommonJS, global)
                   json          JSON representation
+                  json-module   JSON representation as a module (AMD, CommonJS, global)
                   proto2        Protocol Buffers, Version 2
                   proto3        Protocol Buffers, Version 3
-                  static-module Static code without reflection as a module (AMD, CommonJS, global)
                   static        Static code without reflection
+                  static-module Static code without reflection as a module (AMD, CommonJS, global)
 
   -p, --path      Adds a directory to the include path.
 
@@ -403,7 +403,7 @@ protobuf.js integrates into any browserify build-process. There are a few possib
 
 * 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.
-* If your application does not rely on the following modules and/or package size is a concern, you can also exclude `process` , `_process` and `fs`.
+* If your application does not rely on the following modules and package size is a concern, you can also exclude `process` , `_process` and `fs`.
 * If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) as a reference.
 
 Performance

src/codegen.js

@@ -14,7 +14,7 @@ var blockOpenRe  = /[{[]$/,
  * @namespace
  * @function
  * @param {...string} params Function parameter names
- * @returns {CodegenInstance} Codegen instance
+ * @returns {Codegen} Codegen instance
  * @property {boolean} supported Whether code generation is supported by the environment.
  * @property {boolean} verbose=false When set to true, codegen will log generated code to console. Useful for debugging.
  */
@@ -26,11 +26,11 @@ function codegen() {
 
     /**
      * A codegen instance as returned by {@link codegen}, that also is a {@link util.sprintf|sprintf}-like appender function.
-     * @typedef CodegenInstance
+     * @typedef Codegen
      * @type {function}
      * @param {string} format Format string
      * @param {...*} args Replacements
-     * @returns {CodegenInstance} Itself
+     * @returns {Codegen} Itself
      * @property {function(string=):string} str Stringifies the so far generated function source.
      * @property {function(string=, Object=):function} eof Ends generation and builds the function whilst applying a scope.
      */

src/codegen/decode.js

@@ -14,7 +14,17 @@ var Enum    = require("../enum"),
     codegen = require("../codegen");
 
 /**
- * Decodes a message of `this` message's type.
+ * A message decoder as generated by {@link codegen.decode.generate}.
+ * @typedef Decoder
+ * @type {function}
+ * @param {Reader|Uint8Array} readerOrBuffer Reader or buffer to decode from
+ * @param {number} [length] Length of the message, if known beforehand
+ * @returns {Message} Populated runtime message
+ * @this Type
+ */
+
+/**
+ * Fallback {@link Decoder|decoder}.
  * @param {Reader|Uint8Array} readerOrBuffer Reader or buffer to decode from
  * @param {number} [length] Length of the message, if known beforehand
  * @returns {Message} Populated runtime message
@@ -85,9 +95,9 @@ decode.fallback = function decode_fallback(readerOrBuffer, length) {
 };
 
 /**
- * Generates a decoder specific to the specified message type, with an identical signature to {@link codegen.decode.fallback}.
+ * Generates a {@link Decoder|decoder} specific to the specified message type.
  * @param {Type} mtype Message type
- * @returns {CodegenInstance} {@link codegen|Codegen} instance
+ * @returns {Codegen} Codegen instance
  */
 decode.generate = function decode_generate(mtype) {
     /* eslint-disable no-unexpected-multiline */

src/codegen/encode.js

@@ -14,7 +14,17 @@ var Enum    = require("../enum"),
     codegen = require("../codegen");
 
 /**
- * Encodes a message of `this` message's type.
+ * A message encoder as generated by {@link codegen.encode.generate}.
+ * @typedef Encoder
+ * @type {function}
+ * @param {Message|Object} message Runtime message or plain object to encode
+ * @param {Writer} [writer] Writer to encode to
+ * @returns {Writer} writer
+ * @this Type
+ */
+
+/**
+ * Fallback {@link Encoder|encoder}.
  * @param {Message|Object} message Runtime message or plain object to encode
  * @param {Writer} [writer] Writer to encode to
  * @returns {Writer} writer
@@ -93,9 +103,9 @@ encode.fallback = function encode_fallback(message, writer) {
 };
 
 /**
- * Generates an encoder specific to the specified message type, with an identical signature to {@link codegen.encode.fallback}.
+ * Generates an {@link Encoder|encoder} specific to the specified message type.
  * @param {Type} mtype Message type
- * @returns {CodegenInstance} {@link codegen|Codegen} instance
+ * @returns {Codegen} Codegen instance
  */
 encode.generate = function encode_generate(mtype) {
     /* eslint-disable no-unexpected-multiline */

src/codegen/verify.js

@@ -13,6 +13,15 @@ var Enum      = require("../enum"),
     codegen   = require("../codegen");
 var isInteger = util.isInteger;
 
+/**
+ * A message verifier as generated by {@link codegen.verify.generate}.
+ * @typedef Verifier
+ * @type {function}
+ * @param {Message|Object} message Runtime message or plain object to verify
+ * @returns {?string} `null` if valid, otherwise the reason why it is not
+ * @this {Type}
+ */
+
 function invalid(field, expected) {
     return "invalid value for field " + field.getFullName() + " (" + expected + (field.repeated && expected !== "array" ? "[]" : field.map && expected !== "object" ? "{k:"+field.keyType+"}" : "") + " expected)";
 }
@@ -93,7 +102,7 @@ function verifyKey(field, value) {
 }
 
 /**
- * Verifies a runtime message of `this` message type.
+ * Fallback {@link Verifier|verifier}.
  * @param {Message|Object} message Runtime message or plain object to verify
  * @returns {?string} `null` if valid, otherwise the reason why it is not
  * @this {Type}
@@ -230,9 +239,9 @@ function genVerifyKey(gen, field, ref) {
 }
 
 /**
- * Generates a verifier specific to the specified message type, with an identical signature to {@link codegen.verify.fallback}.
+ * Generates a {@link Verifier|verifier} specific to the specified message type.
  * @param {Type} mtype Message type
- * @returns {CodegenInstance} {@link codegen|Codegen} instance
+ * @returns {Codegen} Codegen instance
  */
 verify.generate = function verify_generate(mtype) {
     /* eslint-disable no-unexpected-multiline */