Generate more verbose JSDoc comments for ES6 support, fixes #820

protobufjs · Jun 9, 2017 · cf36097 · cf36097
1 parent f295979
commit cf36097
Show file tree

Hide file tree

Showing 13 changed files with 1,996 additions and 908 deletions.
diff --git a/cli/targets/static.js b/cli/targets/static.js
@@ -394,6 +394,8 @@ function buildType(ref, type) {
                 jsType = "(" + jsType + "|null)";
             pushComment([
                 field.comment || type.name + " " + field.name + ".",
+                "@memberof " + exportName(type),
+                "@instance",
                 "@type {" + jsType + "}"
             ]);
         } else if (firstField) {
@@ -430,7 +432,9 @@ function buildType(ref, type) {
         push("");
         pushComment([
             oneof.comment || type.name + " " + oneof.name + ".",
-            "@name " + exportName(type) + "#" + escapeName(oneof.name),
+            "@property " + escapeName(oneof.name),
+            "@memberof " + exportName(type),
+            "@instance",
             "@type {string|undefined}"
         ]);
         push("Object.defineProperty(" + escapeName(type.name) + ".prototype, " + JSON.stringify(oneof.name) +", {");
@@ -445,6 +449,8 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Creates a new " + type.name + " instance using the specified properties.",
+            "@memberof " + exportName(type),
+            "@static",
             "@param {" + exportName(type, true) + "=} [properties] Properties to set",
             "@returns {" + exportName(type) + "} " + type.name + " instance"
         ]);
@@ -459,6 +465,8 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Encodes the specified " + type.name + " message. Does not implicitly {@link " + exportName(type) + ".verify|verify} messages.",
+            "@memberof " + exportName(type),
+            "@static",
             "@param {" + exportName(type, !config.forceMessage) + "} " + (config.beautify ? "message" : "m") + " " + type.name + " message or plain object to encode",
             "@param {$protobuf.Writer} [" + (config.beautify ? "writer" : "w") + "] Writer to encode to",
             "@returns {$protobuf.Writer} Writer"
@@ -469,6 +477,8 @@ function buildType(ref, type) {
             push("");
             pushComment([
                 "Encodes the specified " + type.name + " message, length delimited. Does not implicitly {@link " + exportName(type) + ".verify|verify} messages.",
+                "@memberof " + exportName(type),
+                "@static",
                 "@param {" + exportName(type, !config.forceMessage) + "} message " + type.name + " message or plain object to encode",
                 "@param {$protobuf.Writer} [writer] Writer to encode to",
                 "@returns {$protobuf.Writer} Writer"
@@ -485,6 +495,8 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Decodes " + aOrAn(type.name) + " message from the specified reader or buffer.",
+            "@memberof " + exportName(type),
+            "@static",
             "@param {$protobuf.Reader|Uint8Array} " + (config.beautify ? "reader" : "r") + " Reader or buffer to decode from",
             "@param {number} [" + (config.beautify ? "length" : "l") + "] Message length if known beforehand",
             "@returns {" + exportName(type) + "} " + type.name,
@@ -497,6 +509,8 @@ function buildType(ref, type) {
             push("");
             pushComment([
                 "Decodes " + aOrAn(type.name) + " message from the specified reader or buffer, length delimited.",
+                "@memberof " + exportName(type),
+                "@static",
                 "@param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from",
                 "@returns {" + exportName(type) + "} " + type.name,
                 "@throws {Error} If the payload is not a reader or valid buffer",
@@ -518,6 +532,8 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Verifies " + aOrAn(type.name) + " message.",
+            "@memberof " + exportName(type),
+            "@static",
             "@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " Plain object to verify",
             "@returns {string|null} `null` if valid, otherwise the reason why it is not"
         ]);
@@ -528,6 +544,8 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Creates " + aOrAn(type.name) + " message from a plain object. Also converts values to their respective internal types.",
+            "@memberof " + exportName(type),
+            "@static",
             "@param {Object.<string,*>} " + (config.beautify ? "object" : "d") + " Plain object",
             "@returns {" + exportName(type) + "} " + type.name
         ]);
@@ -536,6 +554,8 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Creates a plain object from " + aOrAn(type.name) + " message. Also converts values to other types if specified.",
+            "@memberof " + exportName(type),
+            "@static",
             "@param {" + exportName(type) + "} " + (config.beautify ? "message" : "m") + " " + type.name,
             "@param {$protobuf.IConversionOptions} [" + (config.beautify ? "options" : "o") + "] Conversion options",
             "@returns {Object.<string,*>} Plain object"
@@ -545,6 +565,8 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Converts this " + type.name + " to JSON.",
+            "@memberof " + exportName(type),
+            "@instance",
             "@returns {Object.<string,*>} JSON object"
         ]);
         push(escapeName(type.name) + ".prototype.toJSON = function toJSON() {");
@@ -580,6 +602,8 @@ function buildService(ref, service) {
         push("");
         pushComment([
             "Creates new " + service.name + " service using the specified rpc implementation.",
+            "@memberof " + exportName(service),
+            "@static",
             "@param {$protobuf.RPCImpl} rpcImpl RPC implementation",
             "@param {boolean} [requestDelimited=false] Whether requests are length-delimited",
             "@param {boolean} [responseDelimited=false] Whether responses are length-delimited",
@@ -609,9 +633,12 @@ function buildService(ref, service) {
         push("");
         pushComment([
             method.comment || "Calls " + method.name + ".",
+            "@memberof " + exportName(service),
+            "@instance",
             "@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
             "@param {" + exportName(service) + "." + cbName + "} callback Node-style callback called with the error, if any, and " + method.resolvedResponseType.name,
-            "@returns {undefined}"
+            "@returns {undefined}",
+            "@variation 1"
         ]);
         push(escapeName(service.name) + ".prototype" + util.safeProp(lcName) + " = function " + escapeName(lcName) + "(request, callback) {");
             ++indent;
@@ -622,8 +649,9 @@ function buildService(ref, service) {
             push("");
         pushComment([
             method.comment || "Calls " + method.name + ".",
-            "@memberof " + exportName(service) + ".prototype",
             "@function " + lcName,
+            "@memberof " + exportName(service),
+            "@instance",
             "@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
             "@returns {Promise<" + exportName(method.resolvedResponseType) + ">} Promise",
             "@variation 2"

diff --git a/scripts/gentests.js b/scripts/gentests.js
@@ -49,6 +49,7 @@ process.stdout.write("\n");
     { file: "tests/data/mapbox/vector_tile.js" },
     { file: "tests/data/package.js" },
     { file: "tests/data/rpc.js" },
+    { file: "tests/data/rpc-es6.js" },
     { file: "tests/data/test.js" },
     { file: "ext/descriptor/index.js", ext: true }
 ]

diff --git a/tests/data/comments.js b/tests/data/comments.js
@@ -39,24 +39,32 @@ $root.Test1 = (function() {
 
     /**
      * Field with a comment.
+     * @memberof Test1
+     * @instance
      * @type {string}
      */
     Test1.prototype.field1 = "";
 
     /**
      * Test1 field2.
+     * @memberof Test1
+     * @instance
      * @type {number}
      */
     Test1.prototype.field2 = 0;
 
     /**
      * Field with a comment and a <a href="https://example.com/foo/">link</a>
+     * @memberof Test1
+     * @instance
      * @type {boolean}
      */
     Test1.prototype.field3 = false;
 
     /**
      * Creates a new Test1 instance using the specified properties.
+     * @memberof Test1
+     * @static
      * @param {ITest1=} [properties] Properties to set
      * @returns {Test1} Test1 instance
      */
@@ -66,6 +74,8 @@ $root.Test1 = (function() {
 
     /**
      * Encodes the specified Test1 message. Does not implicitly {@link Test1.verify|verify} messages.
+     * @memberof Test1
+     * @static
      * @param {ITest1} message Test1 message or plain object to encode
      * @param {$protobuf.Writer} [writer] Writer to encode to
      * @returns {$protobuf.Writer} Writer
@@ -84,6 +94,8 @@ $root.Test1 = (function() {
 
     /**
      * Encodes the specified Test1 message, length delimited. Does not implicitly {@link Test1.verify|verify} messages.
+     * @memberof Test1
+     * @static
      * @param {ITest1} message Test1 message or plain object to encode
      * @param {$protobuf.Writer} [writer] Writer to encode to
      * @returns {$protobuf.Writer} Writer
@@ -94,6 +106,8 @@ $root.Test1 = (function() {
 
     /**
      * Decodes a Test1 message from the specified reader or buffer.
+     * @memberof Test1
+     * @static
      * @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
      * @param {number} [length] Message length if known beforehand
      * @returns {Test1} Test1
@@ -126,19 +140,23 @@ $root.Test1 = (function() {
 
     /**
      * Decodes a Test1 message from the specified reader or buffer, length delimited.
+     * @memberof Test1
+     * @static
      * @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
      * @returns {Test1} Test1
      * @throws {Error} If the payload is not a reader or valid buffer
      * @throws {$protobuf.util.ProtocolError} If required fields are missing
      */
     Test1.decodeDelimited = function decodeDelimited(reader) {
         if (!(reader instanceof $Reader))
-            reader = $Reader(reader);
+            reader = new $Reader(reader);
         return this.decode(reader, reader.uint32());
     };
 
     /**
      * Verifies a Test1 message.
+     * @memberof Test1
+     * @static
      * @param {Object.<string,*>} message Plain object to verify
      * @returns {string|null} `null` if valid, otherwise the reason why it is not
      */
@@ -159,6 +177,8 @@ $root.Test1 = (function() {
 
     /**
      * Creates a Test1 message from a plain object. Also converts values to their respective internal types.
+     * @memberof Test1
+     * @static
      * @param {Object.<string,*>} object Plain object
      * @returns {Test1} Test1
      */
@@ -177,6 +197,8 @@ $root.Test1 = (function() {
 
     /**
      * Creates a plain object from a Test1 message. Also converts values to other types if specified.
+     * @memberof Test1
+     * @static
      * @param {Test1} message Test1
      * @param {$protobuf.IConversionOptions} [options] Conversion options
      * @returns {Object.<string,*>} Plain object
@@ -201,6 +223,8 @@ $root.Test1 = (function() {
 
     /**
      * Converts this Test1 to JSON.
+     * @memberof Test1
+     * @instance
      * @returns {Object.<string,*>} JSON object
      */
     Test1.prototype.toJSON = function toJSON() {
@@ -234,6 +258,8 @@ $root.Test2 = (function() {
 
     /**
      * Creates a new Test2 instance using the specified properties.
+     * @memberof Test2
+     * @static
      * @param {ITest2=} [properties] Properties to set
      * @returns {Test2} Test2 instance
      */
@@ -243,6 +269,8 @@ $root.Test2 = (function() {
 
     /**
      * Encodes the specified Test2 message. Does not implicitly {@link Test2.verify|verify} messages.
+     * @memberof Test2
+     * @static
      * @param {ITest2} message Test2 message or plain object to encode
      * @param {$protobuf.Writer} [writer] Writer to encode to
      * @returns {$protobuf.Writer} Writer
@@ -255,6 +283,8 @@ $root.Test2 = (function() {
 
     /**
      * Encodes the specified Test2 message, length delimited. Does not implicitly {@link Test2.verify|verify} messages.
+     * @memberof Test2
+     * @static
      * @param {ITest2} message Test2 message or plain object to encode
      * @param {$protobuf.Writer} [writer] Writer to encode to
      * @returns {$protobuf.Writer} Writer
@@ -265,6 +295,8 @@ $root.Test2 = (function() {
 
     /**
      * Decodes a Test2 message from the specified reader or buffer.
+     * @memberof Test2
+     * @static
      * @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
      * @param {number} [length] Message length if known beforehand
      * @returns {Test2} Test2
@@ -288,19 +320,23 @@ $root.Test2 = (function() {
 
     /**
      * Decodes a Test2 message from the specified reader or buffer, length delimited.
+     * @memberof Test2
+     * @static
      * @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
      * @returns {Test2} Test2
      * @throws {Error} If the payload is not a reader or valid buffer
      * @throws {$protobuf.util.ProtocolError} If required fields are missing
      */
     Test2.decodeDelimited = function decodeDelimited(reader) {
         if (!(reader instanceof $Reader))
-            reader = $Reader(reader);
+            reader = new $Reader(reader);
         return this.decode(reader, reader.uint32());
     };
 
     /**
      * Verifies a Test2 message.
+     * @memberof Test2
+     * @static
      * @param {Object.<string,*>} message Plain object to verify
      * @returns {string|null} `null` if valid, otherwise the reason why it is not
      */
@@ -312,6 +348,8 @@ $root.Test2 = (function() {
 
     /**
      * Creates a Test2 message from a plain object. Also converts values to their respective internal types.
+     * @memberof Test2
+     * @static
      * @param {Object.<string,*>} object Plain object
      * @returns {Test2} Test2
      */
@@ -323,6 +361,8 @@ $root.Test2 = (function() {
 
     /**
      * Creates a plain object from a Test2 message. Also converts values to other types if specified.
+     * @memberof Test2
+     * @static
      * @param {Test2} message Test2
      * @param {$protobuf.IConversionOptions} [options] Conversion options
      * @returns {Object.<string,*>} Plain object
@@ -333,6 +373,8 @@ $root.Test2 = (function() {
 
     /**
      * Converts this Test2 to JSON.
+     * @memberof Test2
+     * @instance
      * @returns {Object.<string,*>} JSON object
      */
     Test2.prototype.toJSON = function toJSON() {
@@ -345,7 +387,7 @@ $root.Test2 = (function() {
 /**
  * Test3 enum.
  * @exports Test3
- * @enum {number}
+ * @enum {string}
  * @property {number} ONE=1 Value with a comment.
  * @property {number} TWO=2 TWO value
  * @property {number} THREE=3 Preferred value with a comment.