Skip to content

Commit cf36097

Browse files
dcodeIOdcodeIO
committed
Generate more verbose JSDoc comments for ES6 support, fixes #820 
1 parent f295979 commit cf36097

File tree

13 files changed

+1996
-908
lines changed

13 files changed

+1996
-908
lines changed

‎cli/targets/static.js

+31-3
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,8 @@ function buildType(ref, type) {
394394
jsType = "(" + jsType + "|null)";
395395
pushComment([
396396
field.comment || type.name + " " + field.name + ".",
397+
"@memberof " + exportName(type),
398+
"@instance",
397399
"@type {" + jsType + "}"
398400
]);
399401
} else if (firstField) {
@@ -430,7 +432,9 @@ function buildType(ref, type) {
430432
push("");
431433
pushComment([
432434
oneof.comment || type.name + " " + oneof.name + ".",
433-
"@name " + exportName(type) + "#" + escapeName(oneof.name),
435+
"@property " + escapeName(oneof.name),
436+
"@memberof " + exportName(type),
437+
"@instance",
434438
"@type {string|undefined}"
435439
]);
436440
push("Object.defineProperty(" + escapeName(type.name) + ".prototype, " + JSON.stringify(oneof.name) +", {");
@@ -445,6 +449,8 @@ function buildType(ref, type) {
445449
push("");
446450
pushComment([
447451
"Creates a new " + type.name + " instance using the specified properties.",
452+
"@memberof " + exportName(type),
453+
"@static",
448454
"@param {" + exportName(type, true) + "=} [properties] Properties to set",
449455
"@returns {" + exportName(type) + "} " + type.name + " instance"
450456
]);
@@ -459,6 +465,8 @@ function buildType(ref, type) {
459465
push("");
460466
pushComment([
461467
"Encodes the specified " + type.name + " message. Does not implicitly {@link " + exportName(type) + ".verify|verify} messages.",
468+
"@memberof " + exportName(type),
469+
"@static",
462470
"@param {" + exportName(type, !config.forceMessage) + "} " + (config.beautify ? "message" : "m") + " " + type.name + " message or plain object to encode",
463471
"@param {$protobuf.Writer} [" + (config.beautify ? "writer" : "w") + "] Writer to encode to",
464472
"@returns {$protobuf.Writer} Writer"
@@ -469,6 +477,8 @@ function buildType(ref, type) {
469477
push("");
470478
pushComment([
471479
"Encodes the specified " + type.name + " message, length delimited. Does not implicitly {@link " + exportName(type) + ".verify|verify} messages.",
480+
"@memberof " + exportName(type),
481+
"@static",
472482
"@param {" + exportName(type, !config.forceMessage) + "} message " + type.name + " message or plain object to encode",
473483
"@param {$protobuf.Writer} [writer] Writer to encode to",
474484
"@returns {$protobuf.Writer} Writer"
@@ -485,6 +495,8 @@ function buildType(ref, type) {
485495
push("");
486496
pushComment([
487497
"Decodes " + aOrAn(type.name) + " message from the specified reader or buffer.",
498+
"@memberof " + exportName(type),
499+
"@static",
488500
"@param {$protobuf.Reader|Uint8Array} " + (config.beautify ? "reader" : "r") + " Reader or buffer to decode from",
489501
"@param {number} [" + (config.beautify ? "length" : "l") + "] Message length if known beforehand",
490502
"@returns {" + exportName(type) + "} " + type.name,
@@ -497,6 +509,8 @@ function buildType(ref, type) {
497509
push("");
498510
pushComment([
499511
"Decodes " + aOrAn(type.name) + " message from the specified reader or buffer, length delimited.",
512+
"@memberof " + exportName(type),
513+
"@static",
500514
"@param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from",
501515
"@returns {" + exportName(type) + "} " + type.name,
502516
"@throws {Error} If the payload is not a reader or valid buffer",
@@ -518,6 +532,8 @@ function buildType(ref, type) {
518532
push("");
519533
pushComment([
520534
"Verifies " + aOrAn(type.name) + " message.",
535+
"@memberof " + exportName(type),
536+
"@static",
521537
"@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " Plain object to verify",
522538
"@returns {string|null} `null` if valid, otherwise the reason why it is not"
523539
]);
@@ -528,6 +544,8 @@ function buildType(ref, type) {
528544
push("");
529545
pushComment([
530546
"Creates " + aOrAn(type.name) + " message from a plain object. Also converts values to their respective internal types.",
547+
"@memberof " + exportName(type),
548+
"@static",
531549
"@param {Object.<string,*>} " + (config.beautify ? "object" : "d") + " Plain object",
532550
"@returns {" + exportName(type) + "} " + type.name
533551
]);
@@ -536,6 +554,8 @@ function buildType(ref, type) {
536554
push("");
537555
pushComment([
538556
"Creates a plain object from " + aOrAn(type.name) + " message. Also converts values to other types if specified.",
557+
"@memberof " + exportName(type),
558+
"@static",
539559
"@param {" + exportName(type) + "} " + (config.beautify ? "message" : "m") + " " + type.name,
540560
"@param {$protobuf.IConversionOptions} [" + (config.beautify ? "options" : "o") + "] Conversion options",
541561
"@returns {Object.<string,*>} Plain object"
@@ -545,6 +565,8 @@ function buildType(ref, type) {
545565
push("");
546566
pushComment([
547567
"Converts this " + type.name + " to JSON.",
568+
"@memberof " + exportName(type),
569+
"@instance",
548570
"@returns {Object.<string,*>} JSON object"
549571
]);
550572
push(escapeName(type.name) + ".prototype.toJSON = function toJSON() {");
@@ -580,6 +602,8 @@ function buildService(ref, service) {
580602
push("");
581603
pushComment([
582604
"Creates new " + service.name + " service using the specified rpc implementation.",
605+
"@memberof " + exportName(service),
606+
"@static",
583607
"@param {$protobuf.RPCImpl} rpcImpl RPC implementation",
584608
"@param {boolean} [requestDelimited=false] Whether requests are length-delimited",
585609
"@param {boolean} [responseDelimited=false] Whether responses are length-delimited",
@@ -609,9 +633,12 @@ function buildService(ref, service) {
609633
push("");
610634
pushComment([
611635
method.comment || "Calls " + method.name + ".",
636+
"@memberof " + exportName(service),
637+
"@instance",
612638
"@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
613639
"@param {" + exportName(service) + "." + cbName + "} callback Node-style callback called with the error, if any, and " + method.resolvedResponseType.name,
614-
"@returns {undefined}"
640+
"@returns {undefined}",
641+
"@variation 1"
615642
]);
616643
push(escapeName(service.name) + ".prototype" + util.safeProp(lcName) + " = function " + escapeName(lcName) + "(request, callback) {");
617644
++indent;
@@ -622,8 +649,9 @@ function buildService(ref, service) {
622649
push("");
623650
pushComment([
624651
method.comment || "Calls " + method.name + ".",
625-
"@memberof " + exportName(service) + ".prototype",
626652
"@function " + lcName,
653+
"@memberof " + exportName(service),
654+
"@instance",
627655
"@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
628656
"@returns {Promise<" + exportName(method.resolvedResponseType) + ">} Promise",
629657
"@variation 2"

‎scripts/gentests.js

+1
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ process.stdout.write("\n");
4949
{ file: "tests/data/mapbox/vector_tile.js" },
5050
{ file: "tests/data/package.js" },
5151
{ file: "tests/data/rpc.js" },
52+
{ file: "tests/data/rpc-es6.js" },
5253
{ file: "tests/data/test.js" },
5354
{ file: "ext/descriptor/index.js", ext: true }
5455
]

‎tests/data/comments.js

+45-3
Original file line numberDiff line numberDiff line change
@@ -39,24 +39,32 @@ $root.Test1 = (function() {
3939

4040
/**
4141
* Field with a comment.
42+
* @memberof Test1
43+
* @instance
4244
* @type {string}
4345
*/
4446
Test1.prototype.field1 = "";
4547

4648
/**
4749
* Test1 field2.
50+
* @memberof Test1
51+
* @instance
4852
* @type {number}
4953
*/
5054
Test1.prototype.field2 = 0;
5155

5256
/**
5357
* Field with a comment and a <a href="http://example.com/foo/">link</a>
58+
* @memberof Test1
59+
* @instance
5460
* @type {boolean}
5561
*/
5662
Test1.prototype.field3 = false;
5763

5864
/**
5965
* Creates a new Test1 instance using the specified properties.
66+
* @memberof Test1
67+
* @static
6068
* @param {ITest1=} [properties] Properties to set
6169
* @returns {Test1} Test1 instance
6270
*/
@@ -66,6 +74,8 @@ $root.Test1 = (function() {
6674

6775
/**
6876
* Encodes the specified Test1 message. Does not implicitly {@link Test1.verify|verify} messages.
77+
* @memberof Test1
78+
* @static
6979
* @param {ITest1} message Test1 message or plain object to encode
7080
* @param {$protobuf.Writer} [writer] Writer to encode to
7181
* @returns {$protobuf.Writer} Writer
@@ -84,6 +94,8 @@ $root.Test1 = (function() {
8494

8595
/**
8696
* Encodes the specified Test1 message, length delimited. Does not implicitly {@link Test1.verify|verify} messages.
97+
* @memberof Test1
98+
* @static
8799
* @param {ITest1} message Test1 message or plain object to encode
88100
* @param {$protobuf.Writer} [writer] Writer to encode to
89101
* @returns {$protobuf.Writer} Writer
@@ -94,6 +106,8 @@ $root.Test1 = (function() {
94106

95107
/**
96108
* Decodes a Test1 message from the specified reader or buffer.
109+
* @memberof Test1
110+
* @static
97111
* @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
98112
* @param {number} [length] Message length if known beforehand
99113
* @returns {Test1} Test1
@@ -126,19 +140,23 @@ $root.Test1 = (function() {
126140

127141
/**
128142
* Decodes a Test1 message from the specified reader or buffer, length delimited.
143+
* @memberof Test1
144+
* @static
129145
* @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
130146
* @returns {Test1} Test1
131147
* @throws {Error} If the payload is not a reader or valid buffer
132148
* @throws {$protobuf.util.ProtocolError} If required fields are missing
133149
*/
134150
Test1.decodeDelimited = function decodeDelimited(reader) {
135151
if (!(reader instanceof $Reader))
136-
reader = $Reader(reader);
152+
reader = new $Reader(reader);
137153
return this.decode(reader, reader.uint32());
138154
};
139155

140156
/**
141157
* Verifies a Test1 message.
158+
* @memberof Test1
159+
* @static
142160
* @param {Object.<string,*>} message Plain object to verify
143161
* @returns {string|null} `null` if valid, otherwise the reason why it is not
144162
*/
@@ -159,6 +177,8 @@ $root.Test1 = (function() {
159177

160178
/**
161179
* Creates a Test1 message from a plain object. Also converts values to their respective internal types.
180+
* @memberof Test1
181+
* @static
162182
* @param {Object.<string,*>} object Plain object
163183
* @returns {Test1} Test1
164184
*/
@@ -177,6 +197,8 @@ $root.Test1 = (function() {
177197

178198
/**
179199
* Creates a plain object from a Test1 message. Also converts values to other types if specified.
200+
* @memberof Test1
201+
* @static
180202
* @param {Test1} message Test1
181203
* @param {$protobuf.IConversionOptions} [options] Conversion options
182204
* @returns {Object.<string,*>} Plain object
@@ -201,6 +223,8 @@ $root.Test1 = (function() {
201223

202224
/**
203225
* Converts this Test1 to JSON.
226+
* @memberof Test1
227+
* @instance
204228
* @returns {Object.<string,*>} JSON object
205229
*/
206230
Test1.prototype.toJSON = function toJSON() {
@@ -234,6 +258,8 @@ $root.Test2 = (function() {
234258

235259
/**
236260
* Creates a new Test2 instance using the specified properties.
261+
* @memberof Test2
262+
* @static
237263
* @param {ITest2=} [properties] Properties to set
238264
* @returns {Test2} Test2 instance
239265
*/
@@ -243,6 +269,8 @@ $root.Test2 = (function() {
243269

244270
/**
245271
* Encodes the specified Test2 message. Does not implicitly {@link Test2.verify|verify} messages.
272+
* @memberof Test2
273+
* @static
246274
* @param {ITest2} message Test2 message or plain object to encode
247275
* @param {$protobuf.Writer} [writer] Writer to encode to
248276
* @returns {$protobuf.Writer} Writer
@@ -255,6 +283,8 @@ $root.Test2 = (function() {
255283

256284
/**
257285
* Encodes the specified Test2 message, length delimited. Does not implicitly {@link Test2.verify|verify} messages.
286+
* @memberof Test2
287+
* @static
258288
* @param {ITest2} message Test2 message or plain object to encode
259289
* @param {$protobuf.Writer} [writer] Writer to encode to
260290
* @returns {$protobuf.Writer} Writer
@@ -265,6 +295,8 @@ $root.Test2 = (function() {
265295

266296
/**
267297
* Decodes a Test2 message from the specified reader or buffer.
298+
* @memberof Test2
299+
* @static
268300
* @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
269301
* @param {number} [length] Message length if known beforehand
270302
* @returns {Test2} Test2
@@ -288,19 +320,23 @@ $root.Test2 = (function() {
288320

289321
/**
290322
* Decodes a Test2 message from the specified reader or buffer, length delimited.
323+
* @memberof Test2
324+
* @static
291325
* @param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from
292326
* @returns {Test2} Test2
293327
* @throws {Error} If the payload is not a reader or valid buffer
294328
* @throws {$protobuf.util.ProtocolError} If required fields are missing
295329
*/
296330
Test2.decodeDelimited = function decodeDelimited(reader) {
297331
if (!(reader instanceof $Reader))
298-
reader = $Reader(reader);
332+
reader = new $Reader(reader);
299333
return this.decode(reader, reader.uint32());
300334
};
301335

302336
/**
303337
* Verifies a Test2 message.
338+
* @memberof Test2
339+
* @static
304340
* @param {Object.<string,*>} message Plain object to verify
305341
* @returns {string|null} `null` if valid, otherwise the reason why it is not
306342
*/
@@ -312,6 +348,8 @@ $root.Test2 = (function() {
312348

313349
/**
314350
* Creates a Test2 message from a plain object. Also converts values to their respective internal types.
351+
* @memberof Test2
352+
* @static
315353
* @param {Object.<string,*>} object Plain object
316354
* @returns {Test2} Test2
317355
*/
@@ -323,6 +361,8 @@ $root.Test2 = (function() {
323361

324362
/**
325363
* Creates a plain object from a Test2 message. Also converts values to other types if specified.
364+
* @memberof Test2
365+
* @static
326366
* @param {Test2} message Test2
327367
* @param {$protobuf.IConversionOptions} [options] Conversion options
328368
* @returns {Object.<string,*>} Plain object
@@ -333,6 +373,8 @@ $root.Test2 = (function() {
333373

334374
/**
335375
* Converts this Test2 to JSON.
376+
* @memberof Test2
377+
* @instance
336378
* @returns {Object.<string,*>} JSON object
337379
*/
338380
Test2.prototype.toJSON = function toJSON() {
@@ -345,7 +387,7 @@ $root.Test2 = (function() {
345387
/**
346388
* Test3 enum.
347389
* @exports Test3
348-
* @enum {number}
390+
* @enum {string}
349391
* @property {number} ONE=1 Value with a comment.
350392
* @property {number} TWO=2 TWO value
351393
* @property {number} THREE=3 Preferred value with a comment.

0 commit comments

Comments
 (0)