Skip to content

Commit afefa3d

Browse files
dcodeIOdcodeIO
committed
CLI: Properly implement $Properties interface in JSDoc, see #723 
1 parent a1f23e0 commit afefa3d

File tree

10 files changed

+1353
-159
lines changed

10 files changed

+1353
-159
lines changed

Diff for: ‎README.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -452,11 +452,14 @@ var buffer = AwesomeMessage.encode(message).finish();
452452
...
453453
```
454454

455-
If you'd like to completely exclude long.js and/or node (Buffer) typings, there are two stubs available that can be referenced instead of the full type definitions:
455+
**Note:** By default, the npm package ships with long.js including its typings and node typing as optional dependencies. However, where long.js and/or node Buffers are not required, there are two stubs available that can be referenced instead of the full type definitions:
456456

457457
```ts
458-
/// <reference path="node_modules/protobufjs/stub-long.d.ts" />
459-
/// <reference path="node_modules/protobufjs/stub-node.d.ts" />
458+
/// <reference path="./node_modules/protobufjs/stub-long.d.ts" />
459+
```
460+
461+
```ts
462+
/// <reference path="./node_modules/protobufjs/stub-node.d.ts" />
460463
```
461464

462465
Documentation

Diff for: ‎cli/targets/static.js

+32-20
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,7 @@ function buildFunction(type, functionName, gen, scope) {
251251
}
252252

253253
function toJsType(field) {
254+
var type;
254255
switch (field.type) {
255256
case "double":
256257
case "float":
@@ -259,26 +260,36 @@ function toJsType(field) {
259260
case "sint32":
260261
case "fixed32":
261262
case "sfixed32":
262-
return "number";
263+
type = "number";
264+
break;
263265
case "int64":
264266
case "uint64":
265267
case "sint64":
266268
case "fixed64":
267269
case "sfixed64":
268-
return config["strict-long"] ? "Long" : "number|Long";
270+
type = config["strict-long"] ? "Long" : "number|Long";
271+
break;
269272
case "bool":
270-
return "boolean";
273+
type = "boolean";
274+
break;
271275
case "string":
272-
return "string";
276+
type = "string";
277+
break;
273278
case "bytes":
274-
return "Uint8Array";
279+
type = "Uint8Array";
280+
break;
275281
default:
276282
if (field.resolvedType instanceof Enum)
277-
return "number";
278-
if (field.resolvedType instanceof Type)
279-
return field.resolvedType.fullName.substring(1) + "$Properties";
280-
return "*"; // should not happen
283+
type = field.resolvedType.fullName.substring(1); // reference the enum
284+
else if (field.resolvedType instanceof Type)
285+
type = field.resolvedType.fullName.substring(1) + "$Properties"; // reference the interface
286+
else
287+
type = "*"; // should not happen
288+
break;
281289
}
290+
return field.repeated ? "Array.<" + type + ">"
291+
: field.map ? "Object.<string," + type + ">"
292+
: type;
282293
}
283294

284295
function buildType(ref, type) {
@@ -291,14 +302,10 @@ function buildType(ref, type) {
291302
"@type Object"
292303
];
293304
type.fieldsArray.forEach(function(field) {
294-
var jsType = toJsType(field);
295-
if (field.map)
296-
jsType = "Object.<string," + jsType + ">";
297-
else if (field.repeated)
298-
jsType = "Array.<" + jsType + ">";
299-
var name = util.safeProp(field.name);
300-
name = name.substring(1, name.charAt(0) === "[" ? name.length - 1 : name.length);
301-
typeDef.push("@property {" + jsType + "} " + (field.optional ? "[" + name + "]" : field.name) + " " + (field.comment || type.name + " " + field.name + "."));
305+
var jsType = toJsType(field),
306+
prop = util.safeProp(field.name);
307+
prop = prop.substring(1, prop.charAt(0) === "[" ? prop.length - 1 : prop.length);
308+
typeDef.push("@property {" + jsType + "} " + (field.optional ? "[" + prop + "]" : field.name) + " " + (field.comment || type.name + " " + field.name + "."));
302309
});
303310
push("");
304311
pushComment(typeDef);
@@ -320,14 +327,19 @@ function buildType(ref, type) {
320327
type.fieldsArray.forEach(function(field) {
321328
field.resolve();
322329
var prop = util.safeProp(field.name);
323-
if (firstField) {
330+
if (config.comments) {
331+
push("");
332+
pushComment([
333+
"@type {" + toJsType(field) + (field.optional ? "|undefined" : "") + "}"
334+
]);
335+
} else if (firstField) {
324336
push("");
325337
firstField = false;
326338
}
327339
if (field.repeated)
328-
push(name(type.name) + ".prototype" + prop + " = $util.emptyArray;");
340+
push(name(type.name) + ".prototype" + prop + " = $util.emptyArray;"); // overwritten in constructor
329341
else if (field.map)
330-
push(name(type.name) + ".prototype" + prop + " = $util.emptyObject;");
342+
push(name(type.name) + ".prototype" + prop + " = $util.emptyObject;"); // overwritten in constructor
331343
else if (field.long)
332344
push(name(type.name) + ".prototype" + prop + " = $util.Long ? $util.Long.fromBits("
333345
+ JSON.stringify(field.typeDefault.low) + ","

Diff for: ‎tests/data/comments.js

+11
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,19 @@ $root.Test1 = (function() {
3737
this[keys[i]] = properties[keys[i]];
3838
}
3939

40+
/**
41+
* @type {string|undefined}
42+
*/
4043
Test1.prototype.field1 = "";
44+
45+
/**
46+
* @type {number|undefined}
47+
*/
4148
Test1.prototype.field2 = 0;
49+
50+
/**
51+
* @type {boolean|undefined}
52+
*/
4253
Test1.prototype.field3 = false;
4354

4455
/**

Diff for: ‎tests/data/convert.js

+37-2
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ $root.Message = (function() {
2121
* @property {Array.<number|Long>} [uint64Repeated] Message uint64Repeated.
2222
* @property {Uint8Array} [bytesVal] Message bytesVal.
2323
* @property {Array.<Uint8Array>} [bytesRepeated] Message bytesRepeated.
24-
* @property {number} [enumVal] Message enumVal.
25-
* @property {Array.<number>} [enumRepeated] Message enumRepeated.
24+
* @property {Message.SomeEnum} [enumVal] Message enumVal.
25+
* @property {Array.<Message.SomeEnum>} [enumRepeated] Message enumRepeated.
2626
* @property {Object.<string,number|Long>} [int64Map] Message int64Map.
2727
*/
2828

@@ -44,14 +44,49 @@ $root.Message = (function() {
4444
this[keys[i]] = properties[keys[i]];
4545
}
4646

47+
/**
48+
* @type {string|undefined}
49+
*/
4750
Message.prototype.stringVal = "";
51+
52+
/**
53+
* @type {Array.<string>|undefined}
54+
*/
4855
Message.prototype.stringRepeated = $util.emptyArray;
56+
57+
/**
58+
* @type {number|Long|undefined}
59+
*/
4960
Message.prototype.uint64Val = $util.Long ? $util.Long.fromBits(0,0,true) : 0;
61+
62+
/**
63+
* @type {Array.<number|Long>|undefined}
64+
*/
5065
Message.prototype.uint64Repeated = $util.emptyArray;
66+
67+
/**
68+
* @type {Uint8Array|undefined}
69+
*/
5170
Message.prototype.bytesVal = $util.newBuffer([]);
71+
72+
/**
73+
* @type {Array.<Uint8Array>|undefined}
74+
*/
5275
Message.prototype.bytesRepeated = $util.emptyArray;
76+
77+
/**
78+
* @type {Message.SomeEnum|undefined}
79+
*/
5380
Message.prototype.enumVal = 1;
81+
82+
/**
83+
* @type {Array.<Message.SomeEnum>|undefined}
84+
*/
5485
Message.prototype.enumRepeated = $util.emptyArray;
86+
87+
/**
88+
* @type {Object.<string,number|Long>|undefined}
89+
*/
5590
Message.prototype.int64Map = $util.emptyObject;
5691

5792
/**

Diff for: ‎tests/data/mapbox/vector_tile.js

+69-1
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ $root.vector_tile = (function() {
2424
* Properties of a Tile.
2525
* @typedef vector_tile.Tile$Properties
2626
* @type Object
27-
* @property {Array.<vector_tile.Tile.Layer>} [layers] Tile layers.
27+
* @property {Array.<vector_tile.Tile.Layer$Properties>} [layers] Tile layers.
2828
*/
2929

3030
/**
@@ -41,6 +41,9 @@ $root.vector_tile = (function() {
4141
this[keys[i]] = properties[keys[i]];
4242
}
4343

44+
/**
45+
* @type {Array.<vector_tile.Tile.Layer$Properties>|undefined}
46+
*/
4447
Tile.prototype.layers = $util.emptyArray;
4548

4649
/**
@@ -253,12 +256,39 @@ $root.vector_tile = (function() {
253256
this[keys[i]] = properties[keys[i]];
254257
}
255258

259+
/**
260+
* @type {string|undefined}
261+
*/
256262
Value.prototype.stringValue = "";
263+
264+
/**
265+
* @type {number|undefined}
266+
*/
257267
Value.prototype.floatValue = 0;
268+
269+
/**
270+
* @type {number|undefined}
271+
*/
258272
Value.prototype.doubleValue = 0;
273+
274+
/**
275+
* @type {number|Long|undefined}
276+
*/
259277
Value.prototype.intValue = $util.Long ? $util.Long.fromBits(0,0,false) : 0;
278+
279+
/**
280+
* @type {number|Long|undefined}
281+
*/
260282
Value.prototype.uintValue = $util.Long ? $util.Long.fromBits(0,0,true) : 0;
283+
284+
/**
285+
* @type {number|Long|undefined}
286+
*/
261287
Value.prototype.sintValue = $util.Long ? $util.Long.fromBits(0,0,false) : 0;
288+
289+
/**
290+
* @type {boolean|undefined}
291+
*/
262292
Value.prototype.boolValue = false;
263293

264294
/**
@@ -555,9 +585,24 @@ $root.vector_tile = (function() {
555585
this[keys[i]] = properties[keys[i]];
556586
}
557587

588+
/**
589+
* @type {number|Long|undefined}
590+
*/
558591
Feature.prototype.id = $util.Long ? $util.Long.fromBits(0,0,true) : 0;
592+
593+
/**
594+
* @type {Array.<number>|undefined}
595+
*/
559596
Feature.prototype.tags = $util.emptyArray;
597+
598+
/**
599+
* @type {vector_tile.Tile.GeomType|undefined}
600+
*/
560601
Feature.prototype.type = 0;
602+
603+
/**
604+
* @type {Array.<number>|undefined}
605+
*/
561606
Feature.prototype.geometry = $util.emptyArray;
562607

563608
/**
@@ -861,11 +906,34 @@ $root.vector_tile = (function() {
861906
this[keys[i]] = properties[keys[i]];
862907
}
863908

909+
/**
910+
* @type {number}
911+
*/
864912
Layer.prototype.version = 1;
913+
914+
/**
915+
* @type {string}
916+
*/
865917
Layer.prototype.name = "";
918+
919+
/**
920+
* @type {Array.<vector_tile.Tile.Feature$Properties>|undefined}
921+
*/
866922
Layer.prototype.features = $util.emptyArray;
923+
924+
/**
925+
* @type {Array.<string>|undefined}
926+
*/
867927
Layer.prototype.keys = $util.emptyArray;
928+
929+
/**
930+
* @type {Array.<vector_tile.Tile.Value$Properties>|undefined}
931+
*/
868932
Layer.prototype.values = $util.emptyArray;
933+
934+
/**
935+
* @type {number|undefined}
936+
*/
869937
Layer.prototype.extent = 4096;
870938

871939
/**

0 commit comments

Comments
 (0)