CLI: Annotated callback types in pbjs-generated services, see #582

cli/targets/static.js

@@ -14,6 +14,7 @@ var Type      = protobuf.Type,
 var out = [];
 var indent = 0;
 var config = {};
+var firstService = true;
 
 static_target.description = "Static code without reflection";
 
@@ -47,13 +48,14 @@ function static_target(root, options, callback) {
             push("});");
             --indent;
         push("});");
-        callback(null, out.join('\n'));
+        return callback(null, out.join("\n"));
     } catch (err) {
-        callback(err);
+        return callback(err);
     } finally {
         out = [];
         indent = 0;
         config = {};
+        firstService = true;
     }
 }
 
@@ -63,12 +65,12 @@ function push(line) {
     var ind = "";
     for (var i = 0; i < indent; ++i)
         ind += "    ";
-    out.push(ind + line);
+    return out.push(ind + line);
 }
 
 function pushComment(lines) {
     push("/**");
-    lines.forEach(function(line, i) {
+    lines.forEach(function(line) {
         push(" * " + line);
     });
     push(" */");
@@ -133,7 +135,7 @@ function buildFunction(type, functionName, gen, scope) {
         return field.resolve().resolvedType
             ? JSON.stringify(field.resolvedType.fullName.substring(1))
             : "null";
-    }).join(',') + "]);");
+    }).join(",") + "]);");
     push("return " + lines[0]);
     lines.slice(1).forEach(function(line) {
         var prev = indent;
@@ -366,21 +368,47 @@ function buildType(ref, type) {
 function buildService(ref, service) {
     var fullName = service.fullName.substring(1);
 
+    if (firstService) {
+        firstService = false;
+
+        push("");
+        pushComment([
+             "RPC implementation passed to services performing a service request on network level, i.e. by utilizing http requests or websockets.",
+             "@typedef RPCImpl",
+             "@type {function}",
+             "@param {Method} method Reflected method being called",
+             "@param {Uint8Array} requestData Request data",
+             "@param {RPCCallback} callback Callback function",
+             "@returns {undefined}"
+        ]);
+
+        push("");
+        pushComment([
+             "Node-style callback as used by {@link RPCImpl}.",
+             "@typedef RPCCallback",
+             "@type {function}",
+             "@param {?Error} error Error, if any, otherwise `null`",
+             "@param {Uint8Array} [responseData] Response data or `null` to signal end of stream, if there hasn't been an error",
+             "@returns {undefined}"
+        ]);
+    }
+
     push("");
     pushComment([
         "Constructs a new " + service.name + ".",
         "@exports " + fullName,
         "@constructor",
-        "@param {function(function, Uint8Array, function)} rpc RPC implementation",
+        "@param {RPCImpl} rpc RPC implementation",
         "@param {boolean} [requestDelimited=false] Whether requests are length-delimited",
         "@param {boolean} [responseDelimited=false] Whether responses are length-delimited"
     ]);
     push("function " + name(service.name) + "(rpc, requestDelimited, responseDelimited) {");
     ++indent;
+
     push("");
     pushComment([
         "RPC implementation.",
-        "@type {function(function, Uint8Array, function)}"
+        "@type {RPCImpl}"
     ]);
     push("this.rpc = rpc;");
     push("");
@@ -397,14 +425,24 @@ function buildService(ref, service) {
     push("this.responseDelimited = Boolean(responseDelimited);");
     --indent;
     push("};");
+
     service.getMethodsArray().forEach(function(method) {
         method.resolve();
         var lcName = method.name.substring(0, 1).toLowerCase() + method.name.substring(1);
         push("");
+        var cbName = name(service.name) + "_" + name(lcName) + "_Callback";
+        pushComment([
+            "Callback as used by {@link " + name(service.name) + "#" + name(lcName) + "}.",
+            "@typedef " + cbName,
+            "@type {function}",
+            "@param {?Error} error Error, if any",
+            "@param {" + method.resolvedResponseType.fullName.substring(1) + "} [response] " + method.resolvedResponseType.name
+        ]);
+        push("");
         pushComment([
             "Calls " + method.name + ".",
             "@param {" + method.resolvedRequestType.fullName.substring(1) + "|Object} request " + method.resolvedRequestType.name + " or plain object",
-            "@param {function(?Error, " + method.resolvedResponseType.fullName.substring(1) + "=)} callback Node-style callback called with the error, if any, and " + method.resolvedResponseType.name,
+            "@param {" + cbName + "} callback Node-style callback called with the error, if any, and " + method.resolvedResponseType.name,
             "@returns {undefined}"
         ]);
         push(name(service.name) + ".prototype[" + JSON.stringify(lcName) + "] = function " + name(lcName) + "(request, callback) {");

tests/data/ambiguous-names.js

@@ -188,7 +188,7 @@ $root.B = (function() {
         return function encode(m, w) {
             w||(w=Writer.create())
             if(m["A"]!==undefined&&m["A"]!==null)
-                types[0].encode(m["A"],w.fork()).len&&w.ldelim(1)||w.reset()
+                types[0].encode(m["A"],w.uint32(10).fork()).ldelim()
             return w
         }
         /* eslint-enable */

tests/data/package.js

@@ -173,7 +173,7 @@ $root.Package = (function() {
             if(m["license"]!==undefined&&m["license"]!=="")
                 w.uint32(42).string(m["license"])
             if(m["repository"]!==undefined&&m["repository"]!==null)
-                types[5].encode(m["repository"],w.fork()).len&&w.ldelim(6)||w.reset()
+                types[5].encode(m["repository"],w.uint32(50).fork()).ldelim()
             if(m["bugs"]!==undefined&&m["bugs"]!=="")
                 w.uint32(58).string(m["bugs"])
             if(m["homepage"]!==undefined&&m["homepage"]!=="")

tests/data/rpc.js

@@ -10,19 +10,38 @@ var $root = {};
 
 $root.MyService = (function() {
 
+    /**
+     * RPC implementation passed to services performing a service request on network level, i.e. by utilizing http requests or websockets.
+     * @typedef RPCImpl
+     * @type {function}
+     * @param {Method} method Reflected method being called
+     * @param {Uint8Array} requestData Request data
+     * @param {RPCCallback} callback Callback function
+     * @returns {undefined}
+     */
+
+    /**
+     * Node-style callback as used by {@link RPCImpl}.
+     * @typedef RPCCallback
+     * @type {function}
+     * @param {?Error} error Error, if any, otherwise `null`
+     * @param {Uint8Array} [responseData] Response data or `null` to signal end of stream, if there hasn't been an error
+     * @returns {undefined}
+     */
+
     /**
      * Constructs a new MyService.
      * @exports MyService
      * @constructor
-     * @param {function(function, Uint8Array, function)} rpc RPC implementation
+     * @param {RPCImpl} rpc RPC implementation
      * @param {boolean} [requestDelimited=false] Whether requests are length-delimited
      * @param {boolean} [responseDelimited=false] Whether responses are length-delimited
      */
     function MyService(rpc, requestDelimited, responseDelimited) {
 
         /**
          * RPC implementation.
-         * @type {function(function, Uint8Array, function)}
+         * @type {RPCImpl}
          */
         this.rpc = rpc;
 
@@ -39,10 +58,18 @@ $root.MyService = (function() {
         this.responseDelimited = Boolean(responseDelimited);
     };
 
+    /**
+     * Callback as used by {@link MyService#myMethod}.
+     * @typedef MyService_myMethod_Callback
+     * @type {function}
+     * @param {?Error} error Error, if any
+     * @param {MyResponse} [response] MyResponse
+     */
+
     /**
      * Calls MyMethod.
      * @param {MyRequest|Object} request MyRequest or plain object
-     * @param {function(?Error, MyResponse=)} callback Node-style callback called with the error, if any, and MyResponse
+     * @param {MyService_myMethod_Callback} callback Node-style callback called with the error, if any, and MyResponse
      * @returns {undefined}
      */
     MyService.prototype["myMethod"] = function myMethod(request, callback) {