Skip to content

Commit

Permalink
CLI: Properly implement $Properties interface in JSDoc, see #723
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcodeIO
dcodeIO committed Mar 24, 2017
1 parent a1f23e0 commit afefa3d
Show file tree
Hide file tree
Showing 10 changed files with 1,353 additions and 159 deletions.
9 changes: 6 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -452,11 +452,14 @@ var buffer = AwesomeMessage.encode(message).finish();
...
```

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:
**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:

```ts
/// <reference path="node_modules/protobufjs/stub-long.d.ts" />
/// <reference path="node_modules/protobufjs/stub-node.d.ts" />
/// <reference path="./node_modules/protobufjs/stub-long.d.ts" />
```

```ts
/// <reference path="./node_modules/protobufjs/stub-node.d.ts" />
```

Documentation
Expand Down
52 changes: 32 additions & 20 deletions cli/targets/static.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,7 @@ function buildFunction(type, functionName, gen, scope) {
}

function toJsType(field) {
var type;
switch (field.type) {
case "double":
case "float":
Expand All @@ -259,26 +260,36 @@ function toJsType(field) {
case "sint32":
case "fixed32":
case "sfixed32":
return "number";
type = "number";
break;
case "int64":
case "uint64":
case "sint64":
case "fixed64":
case "sfixed64":
return config["strict-long"] ? "Long" : "number|Long";
type = config["strict-long"] ? "Long" : "number|Long";
break;
case "bool":
return "boolean";
type = "boolean";
break;
case "string":
return "string";
type = "string";
break;
case "bytes":
return "Uint8Array";
type = "Uint8Array";
break;
default:
if (field.resolvedType instanceof Enum)
return "number";
if (field.resolvedType instanceof Type)
return field.resolvedType.fullName.substring(1) + "$Properties";
return "*"; // should not happen
type = field.resolvedType.fullName.substring(1); // reference the enum
else if (field.resolvedType instanceof Type)
type = field.resolvedType.fullName.substring(1) + "$Properties"; // reference the interface
else
type = "*"; // should not happen
break;
}
return field.repeated ? "Array.<" + type + ">"
: field.map ? "Object.<string," + type + ">"
: type;
}

function buildType(ref, type) {
Expand All @@ -291,14 +302,10 @@ function buildType(ref, type) {
"@type Object"
];
type.fieldsArray.forEach(function(field) {
var jsType = toJsType(field);
if (field.map)
jsType = "Object.<string," + jsType + ">";
else if (field.repeated)
jsType = "Array.<" + jsType + ">";
var name = util.safeProp(field.name);
name = name.substring(1, name.charAt(0) === "[" ? name.length - 1 : name.length);
typeDef.push("@property {" + jsType + "} " + (field.optional ? "[" + name + "]" : field.name) + " " + (field.comment || type.name + " " + field.name + "."));
var jsType = toJsType(field),
prop = util.safeProp(field.name);
prop = prop.substring(1, prop.charAt(0) === "[" ? prop.length - 1 : prop.length);
typeDef.push("@property {" + jsType + "} " + (field.optional ? "[" + prop + "]" : field.name) + " " + (field.comment || type.name + " " + field.name + "."));
});
push("");
pushComment(typeDef);
Expand All @@ -320,14 +327,19 @@ function buildType(ref, type) {
type.fieldsArray.forEach(function(field) {
field.resolve();
var prop = util.safeProp(field.name);
if (firstField) {
if (config.comments) {
push("");
pushComment([
"@type {" + toJsType(field) + (field.optional ? "|undefined" : "") + "}"
]);
} else if (firstField) {
push("");
firstField = false;
}
if (field.repeated)
push(name(type.name) + ".prototype" + prop + " = $util.emptyArray;");
push(name(type.name) + ".prototype" + prop + " = $util.emptyArray;"); // overwritten in constructor
else if (field.map)
push(name(type.name) + ".prototype" + prop + " = $util.emptyObject;");
push(name(type.name) + ".prototype" + prop + " = $util.emptyObject;"); // overwritten in constructor
else if (field.long)
push(name(type.name) + ".prototype" + prop + " = $util.Long ? $util.Long.fromBits("
+ JSON.stringify(field.typeDefault.low) + ","
Expand Down
11 changes: 11 additions & 0 deletions tests/data/comments.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,19 @@ $root.Test1 = (function() {
this[keys[i]] = properties[keys[i]];
}

/**
* @type {string|undefined}
*/
Test1.prototype.field1 = "";

/**
* @type {number|undefined}
*/
Test1.prototype.field2 = 0;

/**
* @type {boolean|undefined}
*/
Test1.prototype.field3 = false;

/**
Expand Down
39 changes: 37 additions & 2 deletions tests/data/convert.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ $root.Message = (function() {
* @property {Array.<number|Long>} [uint64Repeated] Message uint64Repeated.
* @property {Uint8Array} [bytesVal] Message bytesVal.
* @property {Array.<Uint8Array>} [bytesRepeated] Message bytesRepeated.
* @property {number} [enumVal] Message enumVal.
* @property {Array.<number>} [enumRepeated] Message enumRepeated.
* @property {Message.SomeEnum} [enumVal] Message enumVal.
* @property {Array.<Message.SomeEnum>} [enumRepeated] Message enumRepeated.
* @property {Object.<string,number|Long>} [int64Map] Message int64Map.
*/

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

/**
* @type {string|undefined}
*/
Message.prototype.stringVal = "";

/**
* @type {Array.<string>|undefined}
*/
Message.prototype.stringRepeated = $util.emptyArray;

/**
* @type {number|Long|undefined}
*/
Message.prototype.uint64Val = $util.Long ? $util.Long.fromBits(0,0,true) : 0;

/**
* @type {Array.<number|Long>|undefined}
*/
Message.prototype.uint64Repeated = $util.emptyArray;

/**
* @type {Uint8Array|undefined}
*/
Message.prototype.bytesVal = $util.newBuffer([]);

/**
* @type {Array.<Uint8Array>|undefined}
*/
Message.prototype.bytesRepeated = $util.emptyArray;

/**
* @type {Message.SomeEnum|undefined}
*/
Message.prototype.enumVal = 1;

/**
* @type {Array.<Message.SomeEnum>|undefined}
*/
Message.prototype.enumRepeated = $util.emptyArray;

/**
* @type {Object.<string,number|Long>|undefined}
*/
Message.prototype.int64Map = $util.emptyObject;

/**
Expand Down
70 changes: 69 additions & 1 deletion tests/data/mapbox/vector_tile.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ $root.vector_tile = (function() {
* Properties of a Tile.
* @typedef vector_tile.Tile$Properties
* @type Object
* @property {Array.<vector_tile.Tile.Layer>} [layers] Tile layers.
* @property {Array.<vector_tile.Tile.Layer$Properties>} [layers] Tile layers.
*/

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

/**
* @type {Array.<vector_tile.Tile.Layer$Properties>|undefined}
*/
Tile.prototype.layers = $util.emptyArray;

/**
Expand Down Expand Up @@ -253,12 +256,39 @@ $root.vector_tile = (function() {
this[keys[i]] = properties[keys[i]];
}

/**
* @type {string|undefined}
*/
Value.prototype.stringValue = "";

/**
* @type {number|undefined}
*/
Value.prototype.floatValue = 0;

/**
* @type {number|undefined}
*/
Value.prototype.doubleValue = 0;

/**
* @type {number|Long|undefined}
*/
Value.prototype.intValue = $util.Long ? $util.Long.fromBits(0,0,false) : 0;

/**
* @type {number|Long|undefined}
*/
Value.prototype.uintValue = $util.Long ? $util.Long.fromBits(0,0,true) : 0;

/**
* @type {number|Long|undefined}
*/
Value.prototype.sintValue = $util.Long ? $util.Long.fromBits(0,0,false) : 0;

/**
* @type {boolean|undefined}
*/
Value.prototype.boolValue = false;

/**
Expand Down Expand Up @@ -555,9 +585,24 @@ $root.vector_tile = (function() {
this[keys[i]] = properties[keys[i]];
}

/**
* @type {number|Long|undefined}
*/
Feature.prototype.id = $util.Long ? $util.Long.fromBits(0,0,true) : 0;

/**
* @type {Array.<number>|undefined}
*/
Feature.prototype.tags = $util.emptyArray;

/**
* @type {vector_tile.Tile.GeomType|undefined}
*/
Feature.prototype.type = 0;

/**
* @type {Array.<number>|undefined}
*/
Feature.prototype.geometry = $util.emptyArray;

/**
Expand Down Expand Up @@ -861,11 +906,34 @@ $root.vector_tile = (function() {
this[keys[i]] = properties[keys[i]];
}

/**
* @type {number}
*/
Layer.prototype.version = 1;

/**
* @type {string}
*/
Layer.prototype.name = "";

/**
* @type {Array.<vector_tile.Tile.Feature$Properties>|undefined}
*/
Layer.prototype.features = $util.emptyArray;

/**
* @type {Array.<string>|undefined}
*/
Layer.prototype.keys = $util.emptyArray;

/**
* @type {Array.<vector_tile.Tile.Value$Properties>|undefined}
*/
Layer.prototype.values = $util.emptyArray;

/**
* @type {number|undefined}
*/
Layer.prototype.extent = 4096;

/**
Expand Down
Loading

0 comments on commit afefa3d

Please sign in to comment.