Also be more verbose when defining properties for ES6, fixes #820

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

Hide file tree

Showing 11 changed files with 1,691 additions and 272 deletions.
diff --git a/cli/targets/static.js b/cli/targets/static.js
@@ -394,9 +394,9 @@ function buildType(ref, type) {
                 jsType = "(" + jsType + "|null)";
             pushComment([
                 field.comment || type.name + " " + field.name + ".",
+                "@member {" + jsType + "}" + escapeName(field.name),
                 "@memberof " + exportName(type),
-                "@instance",
-                "@type {" + jsType + "}"
+                "@instance"
             ]);
         } else if (firstField) {
             push("");
@@ -432,10 +432,9 @@ function buildType(ref, type) {
         push("");
         pushComment([
             oneof.comment || type.name + " " + oneof.name + ".",
-            "@property " + escapeName(oneof.name),
+            "@member {string|undefined} " + escapeName(oneof.name),
             "@memberof " + exportName(type),
-            "@instance",
-            "@type {string|undefined}"
+            "@instance"
         ]);
         push("Object.defineProperty(" + escapeName(type.name) + ".prototype, " + JSON.stringify(oneof.name) +", {");
         ++indent;
@@ -449,6 +448,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Creates a new " + type.name + " instance using the specified properties.",
+            "@function create",
             "@memberof " + exportName(type),
             "@static",
             "@param {" + exportName(type, true) + "=} [properties] Properties to set",
@@ -465,6 +465,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Encodes the specified " + type.name + " message. Does not implicitly {@link " + exportName(type) + ".verify|verify} messages.",
+            "@function encode",
             "@memberof " + exportName(type),
             "@static",
             "@param {" + exportName(type, !config.forceMessage) + "} " + (config.beautify ? "message" : "m") + " " + type.name + " message or plain object to encode",
@@ -477,6 +478,7 @@ function buildType(ref, type) {
             push("");
             pushComment([
                 "Encodes the specified " + type.name + " message, length delimited. Does not implicitly {@link " + exportName(type) + ".verify|verify} messages.",
+                "@function encodeDelimited",
                 "@memberof " + exportName(type),
                 "@static",
                 "@param {" + exportName(type, !config.forceMessage) + "} message " + type.name + " message or plain object to encode",
@@ -495,6 +497,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Decodes " + aOrAn(type.name) + " message from the specified reader or buffer.",
+            "@function decode",
             "@memberof " + exportName(type),
             "@static",
             "@param {$protobuf.Reader|Uint8Array} " + (config.beautify ? "reader" : "r") + " Reader or buffer to decode from",
@@ -509,6 +512,7 @@ function buildType(ref, type) {
             push("");
             pushComment([
                 "Decodes " + aOrAn(type.name) + " message from the specified reader or buffer, length delimited.",
+                "@function decodeDelimited",
                 "@memberof " + exportName(type),
                 "@static",
                 "@param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from",
@@ -532,6 +536,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Verifies " + aOrAn(type.name) + " message.",
+            "@function verify",
             "@memberof " + exportName(type),
             "@static",
             "@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " Plain object to verify",
@@ -544,6 +549,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Creates " + aOrAn(type.name) + " message from a plain object. Also converts values to their respective internal types.",
+            "@function fromObject",
             "@memberof " + exportName(type),
             "@static",
             "@param {Object.<string,*>} " + (config.beautify ? "object" : "d") + " Plain object",
@@ -554,6 +560,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Creates a plain object from " + aOrAn(type.name) + " message. Also converts values to other types if specified.",
+            "@function toObject",
             "@memberof " + exportName(type),
             "@static",
             "@param {" + exportName(type) + "} " + (config.beautify ? "message" : "m") + " " + type.name,
@@ -565,6 +572,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Converts this " + type.name + " to JSON.",
+            "@function toJSON",
             "@memberof " + exportName(type),
             "@instance",
             "@returns {Object.<string,*>} JSON object"
@@ -602,6 +610,7 @@ function buildService(ref, service) {
         push("");
         pushComment([
             "Creates new " + service.name + " service using the specified rpc implementation.",
+            "@function create",
             "@memberof " + exportName(service),
             "@static",
             "@param {$protobuf.RPCImpl} rpcImpl RPC implementation",
@@ -633,6 +642,7 @@ function buildService(ref, service) {
         push("");
         pushComment([
             method.comment || "Calls " + method.name + ".",
+            "@function " + util.safeProp(lcName),
             "@memberof " + exportName(service),
             "@instance",
             "@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",

diff --git a/tests/data/comments.js b/tests/data/comments.js
@@ -39,30 +39,31 @@ $root.Test1 = (function() {
 
     /**
      * Field with a comment.
+     * @member {string}field1
      * @memberof Test1
      * @instance
-     * @type {string}
      */
     Test1.prototype.field1 = "";
 
     /**
      * Test1 field2.
+     * @member {number}field2
      * @memberof Test1
      * @instance
-     * @type {number}
      */
     Test1.prototype.field2 = 0;
 
     /**
      * Field with a comment and a <a href="http://example.com/foo/">link</a>
+     * @member {boolean}field3
      * @memberof Test1
      * @instance
-     * @type {boolean}
      */
     Test1.prototype.field3 = false;
 
     /**
      * Creates a new Test1 instance using the specified properties.
+     * @function create
      * @memberof Test1
      * @static
      * @param {ITest1=} [properties] Properties to set
@@ -74,6 +75,7 @@ $root.Test1 = (function() {
 
     /**
      * Encodes the specified Test1 message. Does not implicitly {@link Test1.verify|verify} messages.
+     * @function encode
      * @memberof Test1
      * @static
      * @param {ITest1} message Test1 message or plain object to encode
@@ -94,6 +96,7 @@ $root.Test1 = (function() {
 
     /**
      * Encodes the specified Test1 message, length delimited. Does not implicitly {@link Test1.verify|verify} messages.
+     * @function encodeDelimited
      * @memberof Test1
      * @static
      * @param {ITest1} message Test1 message or plain object to encode
@@ -106,6 +109,7 @@ $root.Test1 = (function() {
 
     /**
      * Decodes a Test1 message from the specified reader or buffer.
+     * @function decode
      * @memberof Test1
      * @static
      * @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
@@ -140,6 +144,7 @@ $root.Test1 = (function() {
 
     /**
      * Decodes a Test1 message from the specified reader or buffer, length delimited.
+     * @function decodeDelimited
      * @memberof Test1
      * @static
      * @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
@@ -155,6 +160,7 @@ $root.Test1 = (function() {
 
     /**
      * Verifies a Test1 message.
+     * @function verify
      * @memberof Test1
      * @static
      * @param {Object.<string,*>} message Plain object to verify
@@ -177,6 +183,7 @@ $root.Test1 = (function() {
 
     /**
      * Creates a Test1 message from a plain object. Also converts values to their respective internal types.
+     * @function fromObject
      * @memberof Test1
      * @static
      * @param {Object.<string,*>} object Plain object
@@ -197,6 +204,7 @@ $root.Test1 = (function() {
 
     /**
      * Creates a plain object from a Test1 message. Also converts values to other types if specified.
+     * @function toObject
      * @memberof Test1
      * @static
      * @param {Test1} message Test1
@@ -223,6 +231,7 @@ $root.Test1 = (function() {
 
     /**
      * Converts this Test1 to JSON.
+     * @function toJSON
      * @memberof Test1
      * @instance
      * @returns {Object.<string,*>} JSON object
@@ -258,6 +267,7 @@ $root.Test2 = (function() {
 
     /**
      * Creates a new Test2 instance using the specified properties.
+     * @function create
      * @memberof Test2
      * @static
      * @param {ITest2=} [properties] Properties to set
@@ -269,6 +279,7 @@ $root.Test2 = (function() {
 
     /**
      * Encodes the specified Test2 message. Does not implicitly {@link Test2.verify|verify} messages.
+     * @function encode
      * @memberof Test2
      * @static
      * @param {ITest2} message Test2 message or plain object to encode
@@ -283,6 +294,7 @@ $root.Test2 = (function() {
 
     /**
      * Encodes the specified Test2 message, length delimited. Does not implicitly {@link Test2.verify|verify} messages.
+     * @function encodeDelimited
      * @memberof Test2
      * @static
      * @param {ITest2} message Test2 message or plain object to encode
@@ -295,6 +307,7 @@ $root.Test2 = (function() {
 
     /**
      * Decodes a Test2 message from the specified reader or buffer.
+     * @function decode
      * @memberof Test2
      * @static
      * @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
@@ -320,6 +333,7 @@ $root.Test2 = (function() {
 
     /**
      * Decodes a Test2 message from the specified reader or buffer, length delimited.
+     * @function decodeDelimited
      * @memberof Test2
      * @static
      * @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
@@ -335,6 +349,7 @@ $root.Test2 = (function() {
 
     /**
      * Verifies a Test2 message.
+     * @function verify
      * @memberof Test2
      * @static
      * @param {Object.<string,*>} message Plain object to verify
@@ -348,6 +363,7 @@ $root.Test2 = (function() {
 
     /**
      * Creates a Test2 message from a plain object. Also converts values to their respective internal types.
+     * @function fromObject
      * @memberof Test2
      * @static
      * @param {Object.<string,*>} object Plain object
@@ -361,6 +377,7 @@ $root.Test2 = (function() {
 
     /**
      * Creates a plain object from a Test2 message. Also converts values to other types if specified.
+     * @function toObject
      * @memberof Test2
      * @static
      * @param {Test2} message Test2
@@ -373,6 +390,7 @@ $root.Test2 = (function() {
 
     /**
      * Converts this Test2 to JSON.
+     * @function toJSON
      * @memberof Test2
      * @instance
      * @returns {Object.<string,*>} JSON object