Skip to content

Commit 03194c2

Browse files
dcodeIOdcodeIO
committed
Use JSDoc, they said, it documents code, they said. Fixes #770 
1 parent d44a7ee commit 03194c2

12 files changed

Lines changed: 415 additions & 416 deletions

File tree

‎cli/targets/static.js‎

Lines changed: 20 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -121,8 +121,8 @@ function buildNamespace(ref, ns) {
121121
push("");
122122
pushComment([
123123
ns.comment || "Namespace " + ns.name + ".",
124-
"@namespace",
125-
ns.parent instanceof protobuf.Root ? "@name " + escapeName(ns.name) : "@memberof " + exportName(ns.parent),
124+
"@exports " + exportName(ns),
125+
"@namespace"
126126
]);
127127
push((config.es6 ? "const" : "var") + " " + escapeName(ns.name) + " = {};");
128128
}
@@ -348,13 +348,11 @@ function toJsType(field) {
348348
}
349349

350350
function buildType(ref, type) {
351-
var fullName = type.fullName.substring(1);
352351

353352
if (config.comments) {
354353
var typeDef = [
355354
"Properties of " + aOrAn(type.name) + ".",
356-
"@interface I" + escapeName(type.name),
357-
type.parent instanceof protobuf.Root ? "@name I" + escapeName(type.name) : "@memberof " + exportName(type.parent)
355+
"@interface " + exportName(type, true)
358356
];
359357
type.fieldsArray.forEach(function(field) {
360358
var prop = util.safeProp(field.name);
@@ -369,11 +367,10 @@ function buildType(ref, type) {
369367
push("");
370368
pushComment([
371369
"Constructs a new " + type.name + ".",
372-
type.comment ? "@classdesc " + type.comment : null,
370+
"@exports " + exportName(type),
371+
"@classdesc " + (type.comment || "Represents " + aOrAn(type.name)),
373372
"@constructor",
374-
// "@extends $protobuf.Message<" + exportName(type) + ">",
375-
"@param {" + exportName(type, true) + "=} [" + (config.beautify ? "properties" : "p") + "] Properties to set",
376-
type.parent instanceof protobuf.Root ? "@name " + escapeName(type.name) : "@memberof " + exportName(type.parent)
373+
"@param {" + exportName(type, true) + "=} [" + (config.beautify ? "properties" : "p") + "] Properties to set"
377374
]);
378375
buildFunction(type, type.name, Type.generateConstructor(type));
379376

@@ -425,7 +422,7 @@ function buildType(ref, type) {
425422
push("");
426423
pushComment([
427424
oneof.comment || type.name + " " + oneof.name + ".",
428-
"@name " + fullName + "#" + escapeName(oneof.name),
425+
"@name " + exportName(type) + "#" + escapeName(oneof.name),
429426
"@type {string|undefined}"
430427
]);
431428
push("Object.defineProperty(" + escapeName(type.name) + ".prototype, " + JSON.stringify(oneof.name) +", {");
@@ -453,7 +450,7 @@ function buildType(ref, type) {
453450
if (config.encode) {
454451
push("");
455452
pushComment([
456-
"Encodes the specified " + type.name + " message. Does not implicitly {@link " + fullName + ".verify|verify} messages.",
453+
"Encodes the specified " + type.name + " message. Does not implicitly {@link " + exportName(type) + ".verify|verify} messages.",
457454
"@param {" + exportName(type, !config.forceMessage) + "} " + (config.beautify ? "message" : "m") + " " + type.name + " message or plain object to encode",
458455
"@param {$protobuf.Writer} [" + (config.beautify ? "writer" : "w") + "] Writer to encode to",
459456
"@returns {$protobuf.Writer} Writer"
@@ -463,7 +460,7 @@ function buildType(ref, type) {
463460
if (config.delimited) {
464461
push("");
465462
pushComment([
466-
"Encodes the specified " + type.name + " message, length delimited. Does not implicitly {@link " + fullName + ".verify|verify} messages.",
463+
"Encodes the specified " + type.name + " message, length delimited. Does not implicitly {@link " + exportName(type) + ".verify|verify} messages.",
467464
"@param {" + exportName(type, !config.forceMessage) + "} message " + type.name + " message or plain object to encode",
468465
"@param {$protobuf.Writer} [writer] Writer to encode to",
469466
"@returns {$protobuf.Writer} Writer"
@@ -482,7 +479,7 @@ function buildType(ref, type) {
482479
"Decodes " + aOrAn(type.name) + " message from the specified reader or buffer.",
483480
"@param {$protobuf.Reader|Uint8Array} " + (config.beautify ? "reader" : "r") + " Reader or buffer to decode from",
484481
"@param {number} [" + (config.beautify ? "length" : "l") + "] Message length if known beforehand",
485-
"@returns {" + fullName + "} " + type.name,
482+
"@returns {" + exportName(type) + "} " + type.name,
486483
"@throws {Error} If the payload is not a reader or valid buffer",
487484
"@throws {$protobuf.util.ProtocolError} If required fields are missing"
488485
]);
@@ -493,7 +490,7 @@ function buildType(ref, type) {
493490
pushComment([
494491
"Decodes " + aOrAn(type.name) + " message from the specified reader or buffer, length delimited.",
495492
"@param {$protobuf.Reader|Uint8Array} reader Reader or buffer to decode from",
496-
"@returns {" + fullName + "} " + type.name,
493+
"@returns {" + exportName(type) + "} " + type.name,
497494
"@throws {Error} If the payload is not a reader or valid buffer",
498495
"@throws {$protobuf.util.ProtocolError} If required fields are missing"
499496
]);
@@ -524,14 +521,14 @@ function buildType(ref, type) {
524521
pushComment([
525522
"Creates " + aOrAn(type.name) + " message from a plain object. Also converts values to their respective internal types.",
526523
"@param {Object.<string,*>} " + (config.beautify ? "object" : "d") + " Plain object",
527-
"@returns {" + fullName + "} " + type.name
524+
"@returns {" + exportName(type) + "} " + type.name
528525
]);
529526
buildFunction(type, "fromObject", protobuf.converter.fromObject(type));
530527

531528
push("");
532529
pushComment([
533530
"Creates a plain object from " + aOrAn(type.name) + " message. Also converts values to other types if specified.",
534-
"@param {" + fullName + "} " + (config.beautify ? "message" : "m") + " " + type.name,
531+
"@param {" + exportName(type) + "} " + (config.beautify ? "message" : "m") + " " + type.name,
535532
"@param {$protobuf.IConversionOptions} [" + (config.beautify ? "options" : "o") + "] Conversion options",
536533
"@returns {Object.<string,*>} Plain object"
537534
]);
@@ -555,13 +552,13 @@ function buildService(ref, service) {
555552
push("");
556553
pushComment([
557554
"Constructs a new " + service.name + " service.",
558-
service.comment ? "@classdesc " + service.comment : null,
555+
"@exports " + exportName(service),
556+
"@classdesc " + (service.comment || "Represents " + aOrAn(service.name)),
559557
"@extends $protobuf.rpc.Service",
560558
"@constructor",
561559
"@param {$protobuf.RPCImpl} rpcImpl RPC implementation",
562560
"@param {boolean} [requestDelimited=false] Whether requests are length-delimited",
563-
"@param {boolean} [responseDelimited=false] Whether responses are length-delimited",
564-
service.parent instanceof protobuf.Root ? "@name " + escapeName(service.name) : "@memberof " + exportName(service.parent)
561+
"@param {boolean} [responseDelimited=false] Whether responses are length-delimited"
565562
]);
566563
push("function " + escapeName(service.name) + "(rpcImpl, requestDelimited, responseDelimited) {");
567564
++indent;
@@ -598,7 +595,7 @@ function buildService(ref, service) {
598595
"@typedef " + cbName,
599596
"@type {function}",
600597
"@param {Error|null} error Error, if any",
601-
"@param {" + method.resolvedResponseType.fullName.substring(1) + "} [response] " + method.resolvedResponseType.name
598+
"@param {" + exportName(method.resolvedResponseType) + "} [response] " + method.resolvedResponseType.name
602599
]);
603600
push("");
604601
pushComment([
@@ -609,15 +606,14 @@ function buildService(ref, service) {
609606
]);
610607
push(escapeName(service.name) + ".prototype" + util.safeProp(lcName) + " = function " + escapeName(lcName) + "(request, callback) {");
611608
++indent;
612-
push("return this.rpcCall(" + escapeName(lcName) + ", $root" + method.resolvedRequestType.fullName + ", $root" + method.resolvedResponseType.fullName + ", request, callback);");
609+
push("return this.rpcCall(" + escapeName(lcName) + ", $root." + exportName(method.resolvedRequestType) + ", $root." + exportName(method.resolvedResponseType) + ", request, callback);");
613610
--indent;
614611
push("};");
615612
if (config.comments)
616613
push("");
617614
pushComment([
618615
method.comment || "Calls " + method.name + ".",
619-
"@name " + escapeName(service.name) + "#" + lcName,
620-
"@function",
616+
"@function " + escapeName(service.name) + "#" + lcName,
621617
"@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
622618
"@returns {Promise<" + exportName(method.resolvedResponseType) + ">} Promise",
623619
"@variation 2"
@@ -630,9 +626,7 @@ function buildEnum(ref, enm) {
630626
push("");
631627
var comment = [
632628
enm.comment || enm.name + " enum.",
633-
"@name " + escapeName(enm.name),
634-
"@enum {number}",
635-
enm.parent instanceof protobuf.Root ? "@name " + escapeName(enm.name) : "@memberof " + exportName(enm.parent)
629+
"@enum {number} " + exportName(enm)
636630
];
637631
Object.keys(enm.values).forEach(function(key) {
638632
var val = enm.values[key];

‎index.d.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1183,6 +1183,13 @@ export class Root extends NamespaceBase {
11831183
*/
11841184
public load(filename: (string|string[]), options: IParseOptions, callback: LoadCallback): void;
11851185

1186+
/**
1187+
* Loads one or multiple .proto or preprocessed .json files into this root namespace and calls the callback.
1188+
* @param filename Names of one or multiple files to load
1189+
* @param callback Callback function
1190+
*/
1191+
public load(filename: (string|string[]), callback: LoadCallback): void;
1192+
11861193
/**
11871194
* Loads one or multiple .proto or preprocessed .json files into this root namespace and returns a promise.
11881195
* @param filename Names of one or multiple files to load

‎src/root.js‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,7 @@ Root.prototype.load = function load(filename, options, callback) {
203203

204204
/**
205205
* Loads one or multiple .proto or preprocessed .json files into this root namespace and calls the callback.
206+
* @function Root#load
206207
* @param {string|string[]} filename Names of one or multiple files to load
207208
* @param {LoadCallback} callback Callback function
208209
* @returns {undefined}
@@ -212,8 +213,7 @@ Root.prototype.load = function load(filename, options, callback) {
212213

213214
/**
214215
* Loads one or multiple .proto or preprocessed .json files into this root namespace and returns a promise.
215-
* @name Root#load
216-
* @function
216+
* @function Root#load
217217
* @param {string|string[]} filename Names of one or multiple files to load
218218
* @param {IParseOptions} [options] Parse options. Defaults to {@link parse.defaults} when omitted.
219219
* @returns {Promise<Root>} Promise
@@ -223,8 +223,7 @@ Root.prototype.load = function load(filename, options, callback) {
223223

224224
/**
225225
* Synchronously loads one or multiple .proto or preprocessed .json files into this root namespace (node only).
226-
* @name Root#loadSync
227-
* @function
226+
* @function Root#loadSync
228227
* @param {string|string[]} filename Names of one or multiple files to load
229228
* @param {IParseOptions} [options] Parse options. Defaults to {@link parse.defaults} when omitted.
230229
* @returns {Root} Root namespace

‎tests/data/comments.js‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,21 +14,20 @@ $root.Test1 = (function() {
1414
/**
1515
* Properties of a Test1.
1616
* @interface ITest1
17-
* @name ITest1
1817
* @property {string} [field1] Field with a comment.
1918
* @property {number} [field2] Test1 field2.
2019
* @property {boolean} [field3] Field with a comment and a <a href="http://example.com/foo/">link</a>
2120
*/
2221

2322
/**
2423
* Constructs a new Test1.
24+
* @exports Test1
2525
* @classdesc Message
2626
* with
2727
* a
2828
* comment.
2929
* @constructor
3030
* @param {ITest1=} [properties] Properties to set
31-
* @name Test1
3231
*/
3332
function Test1(properties) {
3433
if (properties)
@@ -140,7 +139,7 @@ $root.Test1 = (function() {
140139
/**
141140
* Verifies a Test1 message.
142141
* @param {Object.<string,*>} message Plain object to verify
143-
* @returns {?string} `null` if valid, otherwise the reason why it is not
142+
* @returns {string|null} `null` if valid, otherwise the reason why it is not
144143
*/
145144
Test1.verify = function verify(message) {
146145
if (typeof message !== "object" || message === null)
@@ -215,14 +214,14 @@ $root.Test2 = (function() {
215214
/**
216215
* Properties of a Test2.
217216
* @interface ITest2
218-
* @name ITest2
219217
*/
220218

221219
/**
222220
* Constructs a new Test2.
221+
* @exports Test2
222+
* @classdesc Represents a Test2
223223
* @constructor
224224
* @param {ITest2=} [properties] Properties to set
225-
* @name Test2
226225
*/
227226
function Test2(properties) {
228227
if (properties)
@@ -301,7 +300,7 @@ $root.Test2 = (function() {
301300
/**
302301
* Verifies a Test2 message.
303302
* @param {Object.<string,*>} message Plain object to verify
304-
* @returns {?string} `null` if valid, otherwise the reason why it is not
303+
* @returns {string|null} `null` if valid, otherwise the reason why it is not
305304
*/
306305
Test2.verify = function verify(message) {
307306
if (typeof message !== "object" || message === null)
@@ -343,18 +342,18 @@ $root.Test2 = (function() {
343342

344343
/**
345344
* Test3 enum.
346-
* @name Test3
347-
* @enum {number}
348-
* @name Test3
345+
* @enum {number} Test3
349346
* @property {number} ONE=1 Value with a comment.
350347
* @property {number} TWO=2 TWO value
351-
* @property {number} THREE=3 Value with a comment.
348+
* @property {number} THREE=3 Preferred value with a comment.
349+
* @property {number} FOUR=4 Other value with a comment.
352350
*/
353351
$root.Test3 = (function() {
354352
var valuesById = {}, values = Object.create(valuesById);
355353
values[valuesById[1] = "ONE"] = 1;
356354
values[valuesById[2] = "TWO"] = 2;
357355
values[valuesById[3] = "THREE"] = 3;
356+
values[valuesById[4] = "FOUR"] = 4;
358357
return values;
359358
})();
360359

‎tests/data/convert.js‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@ $root.Message = (function() {
1414
/**
1515
* Properties of a Message.
1616
* @interface IMessage
17-
* @name IMessage
1817
* @property {string} [stringVal] Message stringVal.
1918
* @property {Array.<string>} [stringRepeated] Message stringRepeated.
2019
* @property {number|Long} [uint64Val] Message uint64Val.
@@ -28,9 +27,10 @@ $root.Message = (function() {
2827

2928
/**
3029
* Constructs a new Message.
30+
* @exports Message
31+
* @classdesc Represents a Message
3132
* @constructor
3233
* @param {IMessage=} [properties] Properties to set
33-
* @name Message
3434
*/
3535
function Message(properties) {
3636
this.stringRepeated = [];
@@ -247,7 +247,7 @@ $root.Message = (function() {
247247
/**
248248
* Verifies a Message message.
249249
* @param {Object.<string,*>} message Plain object to verify
250-
* @returns {?string} `null` if valid, otherwise the reason why it is not
250+
* @returns {string|null} `null` if valid, otherwise the reason why it is not
251251
*/
252252
Message.verify = function verify(message) {
253253
if (typeof message !== "object" || message === null)
@@ -497,9 +497,7 @@ $root.Message = (function() {
497497

498498
/**
499499
* SomeEnum enum.
500-
* @name SomeEnum
501-
* @enum {number}
502-
* @memberof Message
500+
* @enum {number} Message.SomeEnum
503501
* @property {number} ONE=1 ONE value
504502
* @property {number} TWO=2 TWO value
505503
*/

0 commit comments

Comments
 (0)