Skip to content

Commit 13bf9c2

Browse files
dcodeIOdcodeIO
committed
CLI: Various improvements to statically generated JSDoc, also fixes #772 
1 parent 03194c2 commit 13bf9c2

9 files changed

Lines changed: 561 additions & 475 deletions

File tree

‎cli/targets/static.js‎

Lines changed: 24 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,11 @@ function static_target(root, options, callback) {
3636
push("");
3737
}
3838
if (config.comments) {
39-
if (root.comment)
39+
if (root.comment) {
4040
pushComment("@fileoverview " + root.comment);
41-
else
42-
push("// Exported root namespace");
41+
push("");
42+
}
43+
push("// Exported root namespace");
4344
}
4445
var rootProp = cliUtil.safeProp(config.root || "default");
4546
push((config.es6 ? "const" : "var") + " $root = $protobuf.roots" + rootProp + " || ($protobuf.roots" + rootProp + " = {});");
@@ -80,13 +81,18 @@ function pushComment(lines) {
8081
}
8182

8283
function exportName(object, asInterface) {
84+
if (asInterface) {
85+
if (object.__interfaceName)
86+
return object.__interfaceName;
87+
} else if (object.__exportName)
88+
return object.__exportName;
8389
var parts = object.fullName.substring(1).split("."),
8490
i = 0;
8591
while (i < parts.length)
8692
parts[i] = escapeName(parts[i++]);
8793
if (asInterface)
8894
parts[i - 1] = "I" + parts[i - 1];
89-
return parts.join(".");
95+
return object[asInterface ? "__interfaceName" : "__exportName"] = parts.join(".");
9096
}
9197

9298
function escapeName(name) {
@@ -121,7 +127,7 @@ function buildNamespace(ref, ns) {
121127
push("");
122128
pushComment([
123129
ns.comment || "Namespace " + ns.name + ".",
124-
"@exports " + exportName(ns),
130+
ns.parent instanceof protobuf.Root ? "@exports " + escapeName(ns.name) : "@memberof " + exportName(ns.parent),
125131
"@namespace"
126132
]);
127133
push((config.es6 ? "const" : "var") + " " + escapeName(ns.name) + " = {};");
@@ -352,12 +358,13 @@ function buildType(ref, type) {
352358
if (config.comments) {
353359
var typeDef = [
354360
"Properties of " + aOrAn(type.name) + ".",
355-
"@interface " + exportName(type, true)
361+
type.parent instanceof protobuf.Root ? "@exports " + escapeName("I" + type.name) : "@memberof " + exportName(type.parent),
362+
"@interface " + escapeName("I" + type.name)
356363
];
357364
type.fieldsArray.forEach(function(field) {
358365
var prop = util.safeProp(field.name);
359366
prop = prop.substring(1, prop.charAt(0) === "[" ? prop.length - 1 : prop.length);
360-
typeDef.push("@property {" + toJsType(field) + "} " + (field.optional ? "[" + prop + "]" : field.name) + " " + (field.comment || type.name + " " + field.name + "."));
367+
typeDef.push("@property {" + toJsType(field) + "} " + (field.optional ? "[" + prop + "]" : field.name) + " " + (field.comment || type.name + " " + field.name));
361368
});
362369
push("");
363370
pushComment(typeDef);
@@ -367,8 +374,8 @@ function buildType(ref, type) {
367374
push("");
368375
pushComment([
369376
"Constructs a new " + type.name + ".",
370-
"@exports " + exportName(type),
371-
"@classdesc " + (type.comment || "Represents " + aOrAn(type.name)),
377+
type.parent instanceof protobuf.Root ? "@exports " + escapeName(type.name) : "@memberof " + exportName(type.parent),
378+
"@classdesc " + (type.comment || "Represents " + aOrAn(type.name) + "."),
372379
"@constructor",
373380
"@param {" + exportName(type, true) + "=} [" + (config.beautify ? "properties" : "p") + "] Properties to set"
374381
]);
@@ -552,7 +559,7 @@ function buildService(ref, service) {
552559
push("");
553560
pushComment([
554561
"Constructs a new " + service.name + " service.",
555-
"@exports " + exportName(service),
562+
service.parent instanceof protobuf.Root ? "@exports " + escapeName(service.name) : "@memberof " + exportName(service.parent),
556563
"@classdesc " + (service.comment || "Represents " + aOrAn(service.name)),
557564
"@extends $protobuf.rpc.Service",
558565
"@constructor",
@@ -586,12 +593,13 @@ function buildService(ref, service) {
586593

587594
service.methodsArray.forEach(function(method) {
588595
method.resolve();
589-
var lcName = method.name.substring(0, 1).toLowerCase() + method.name.substring(1);
596+
var lcName = protobuf.util.lcFirst(method.name),
597+
cbName = escapeName(method.name + "Callback");
590598
push("");
591-
var cbName = escapeName(service.name) + "_" + escapeName(lcName) + "_Callback";
592599
pushComment([
593-
"Callback as used by {@link " + escapeName(service.name) + "#" + escapeName(lcName) + "}.",
600+
"Callback as used by {@link " + exportName(service) + "#" + escapeName(lcName) + "}.",
594601
// This is a more specialized version of protobuf.rpc.ServiceCallback
602+
"@memberof " + exportName(service),
595603
"@typedef " + cbName,
596604
"@type {function}",
597605
"@param {Error|null} error Error, if any",
@@ -601,7 +609,7 @@ function buildService(ref, service) {
601609
pushComment([
602610
method.comment || "Calls " + method.name + ".",
603611
"@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
604-
"@param {" + cbName + "} callback Node-style callback called with the error, if any, and " + method.resolvedResponseType.name,
612+
"@param {" + exportName(service) + "." + cbName + "} callback Node-style callback called with the error, if any, and " + method.resolvedResponseType.name,
605613
"@returns {undefined}"
606614
]);
607615
push(escapeName(service.name) + ".prototype" + util.safeProp(lcName) + " = function " + escapeName(lcName) + "(request, callback) {");
@@ -613,7 +621,8 @@ function buildService(ref, service) {
613621
push("");
614622
pushComment([
615623
method.comment || "Calls " + method.name + ".",
616-
"@function " + escapeName(service.name) + "#" + lcName,
624+
"@memberof " + exportName(service) + ".prototype",
625+
"@function " + lcName,
617626
"@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
618627
"@returns {Promise<" + exportName(method.resolvedResponseType) + ">} Promise",
619628
"@variation 2"

‎tests/data/comments.js‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,10 @@ $root.Test1 = (function() {
1313

1414
/**
1515
* Properties of a Test1.
16+
* @exports ITest1
1617
* @interface ITest1
1718
* @property {string} [field1] Field with a comment.
18-
* @property {number} [field2] Test1 field2.
19+
* @property {number} [field2] Test1 field2
1920
* @property {boolean} [field3] Field with a comment and a <a href="http://example.com/foo/">link</a>
2021
*/
2122

@@ -213,13 +214,14 @@ $root.Test2 = (function() {
213214

214215
/**
215216
* Properties of a Test2.
217+
* @exports ITest2
216218
* @interface ITest2
217219
*/
218220

219221
/**
220222
* Constructs a new Test2.
221223
* @exports Test2
222-
* @classdesc Represents a Test2
224+
* @classdesc Represents a Test2.
223225
* @constructor
224226
* @param {ITest2=} [properties] Properties to set
225227
*/

‎tests/data/convert.js‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,22 +13,23 @@ $root.Message = (function() {
1313

1414
/**
1515
* Properties of a Message.
16+
* @exports IMessage
1617
* @interface IMessage
17-
* @property {string} [stringVal] Message stringVal.
18-
* @property {Array.<string>} [stringRepeated] Message stringRepeated.
19-
* @property {number|Long} [uint64Val] Message uint64Val.
20-
* @property {Array.<number|Long>} [uint64Repeated] Message uint64Repeated.
21-
* @property {Uint8Array} [bytesVal] Message bytesVal.
22-
* @property {Array.<Uint8Array>} [bytesRepeated] Message bytesRepeated.
23-
* @property {Message.SomeEnum} [enumVal] Message enumVal.
24-
* @property {Array.<Message.SomeEnum>} [enumRepeated] Message enumRepeated.
25-
* @property {Object.<string,number|Long>} [int64Map] Message int64Map.
18+
* @property {string} [stringVal] Message stringVal
19+
* @property {Array.<string>} [stringRepeated] Message stringRepeated
20+
* @property {number|Long} [uint64Val] Message uint64Val
21+
* @property {Array.<number|Long>} [uint64Repeated] Message uint64Repeated
22+
* @property {Uint8Array} [bytesVal] Message bytesVal
23+
* @property {Array.<Uint8Array>} [bytesRepeated] Message bytesRepeated
24+
* @property {Message.SomeEnum} [enumVal] Message enumVal
25+
* @property {Array.<Message.SomeEnum>} [enumRepeated] Message enumRepeated
26+
* @property {Object.<string,number|Long>} [int64Map] Message int64Map
2627
*/
2728

2829
/**
2930
* Constructs a new Message.
3031
* @exports Message
31-
* @classdesc Represents a Message
32+
* @classdesc Represents a Message.
3233
* @constructor
3334
* @param {IMessage=} [properties] Properties to set
3435
*/

‎tests/data/mapbox/vector_tile.js‎

Lines changed: 34 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,15 @@ $root.vector_tile = (function() {
2222

2323
/**
2424
* Properties of a Tile.
25-
* @interface vector_tile.ITile
26-
* @property {Array.<vector_tile.Tile.ILayer>} [layers] Tile layers.
25+
* @memberof vector_tile
26+
* @interface ITile
27+
* @property {Array.<vector_tile.Tile.ILayer>} [layers] Tile layers
2728
*/
2829

2930
/**
3031
* Constructs a new Tile.
31-
* @exports vector_tile.Tile
32-
* @classdesc Represents a Tile
32+
* @memberof vector_tile
33+
* @classdesc Represents a Tile.
3334
* @constructor
3435
* @param {vector_tile.ITile=} [properties] Properties to set
3536
*/
@@ -213,20 +214,21 @@ $root.vector_tile = (function() {
213214

214215
/**
215216
* Properties of a Value.
216-
* @interface vector_tile.Tile.IValue
217-
* @property {string} [stringValue] Value stringValue.
218-
* @property {number} [floatValue] Value floatValue.
219-
* @property {number} [doubleValue] Value doubleValue.
220-
* @property {number|Long} [intValue] Value intValue.
221-
* @property {number|Long} [uintValue] Value uintValue.
222-
* @property {number|Long} [sintValue] Value sintValue.
223-
* @property {boolean} [boolValue] Value boolValue.
217+
* @memberof vector_tile.Tile
218+
* @interface IValue
219+
* @property {string} [stringValue] Value stringValue
220+
* @property {number} [floatValue] Value floatValue
221+
* @property {number} [doubleValue] Value doubleValue
222+
* @property {number|Long} [intValue] Value intValue
223+
* @property {number|Long} [uintValue] Value uintValue
224+
* @property {number|Long} [sintValue] Value sintValue
225+
* @property {boolean} [boolValue] Value boolValue
224226
*/
225227

226228
/**
227229
* Constructs a new Value.
228-
* @exports vector_tile.Tile.Value
229-
* @classdesc Represents a Value
230+
* @memberof vector_tile.Tile
231+
* @classdesc Represents a Value.
230232
* @constructor
231233
* @param {vector_tile.Tile.IValue=} [properties] Properties to set
232234
*/
@@ -532,17 +534,18 @@ $root.vector_tile = (function() {
532534

533535
/**
534536
* Properties of a Feature.
535-
* @interface vector_tile.Tile.IFeature
536-
* @property {number|Long} [id] Feature id.
537-
* @property {Array.<number>} [tags] Feature tags.
538-
* @property {vector_tile.Tile.GeomType} [type] Feature type.
539-
* @property {Array.<number>} [geometry] Feature geometry.
537+
* @memberof vector_tile.Tile
538+
* @interface IFeature
539+
* @property {number|Long} [id] Feature id
540+
* @property {Array.<number>} [tags] Feature tags
541+
* @property {vector_tile.Tile.GeomType} [type] Feature type
542+
* @property {Array.<number>} [geometry] Feature geometry
540543
*/
541544

542545
/**
543546
* Constructs a new Feature.
544-
* @exports vector_tile.Tile.Feature
545-
* @classdesc Represents a Feature
547+
* @memberof vector_tile.Tile
548+
* @classdesc Represents a Feature.
546549
* @constructor
547550
* @param {vector_tile.Tile.IFeature=} [properties] Properties to set
548551
*/
@@ -836,19 +839,20 @@ $root.vector_tile = (function() {
836839

837840
/**
838841
* Properties of a Layer.
839-
* @interface vector_tile.Tile.ILayer
840-
* @property {number} version Layer version.
841-
* @property {string} name Layer name.
842-
* @property {Array.<vector_tile.Tile.IFeature>} [features] Layer features.
843-
* @property {Array.<string>} [keys] Layer keys.
844-
* @property {Array.<vector_tile.Tile.IValue>} [values] Layer values.
845-
* @property {number} [extent] Layer extent.
842+
* @memberof vector_tile.Tile
843+
* @interface ILayer
844+
* @property {number} version Layer version
845+
* @property {string} name Layer name
846+
* @property {Array.<vector_tile.Tile.IFeature>} [features] Layer features
847+
* @property {Array.<string>} [keys] Layer keys
848+
* @property {Array.<vector_tile.Tile.IValue>} [values] Layer values
849+
* @property {number} [extent] Layer extent
846850
*/
847851

848852
/**
849853
* Constructs a new Layer.
850-
* @exports vector_tile.Tile.Layer
851-
* @classdesc Represents a Layer
854+
* @memberof vector_tile.Tile
855+
* @classdesc Represents a Layer.
852856
* @constructor
853857
* @param {vector_tile.Tile.ILayer=} [properties] Properties to set
854858
*/

‎tests/data/package.js‎

Lines changed: 25 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -13,30 +13,31 @@ $root.Package = (function() {
1313

1414
/**
1515
* Properties of a Package.
16+
* @exports IPackage
1617
* @interface IPackage
17-
* @property {string} [name] Package name.
18-
* @property {string} [version] Package version.
19-
* @property {string} [versionScheme] Package versionScheme.
20-
* @property {string} [description] Package description.
21-
* @property {string} [author] Package author.
22-
* @property {string} [license] Package license.
23-
* @property {Package.IRepository} [repository] Package repository.
24-
* @property {string} [bugs] Package bugs.
25-
* @property {string} [homepage] Package homepage.
26-
* @property {Array.<string>} [keywords] Package keywords.
27-
* @property {string} [main] Package main.
28-
* @property {Object.<string,string>} [bin] Package bin.
29-
* @property {Object.<string,string>} [scripts] Package scripts.
30-
* @property {Object.<string,string>} [dependencies] Package dependencies.
31-
* @property {Object.<string,string>} [devDependencies] Package devDependencies.
32-
* @property {string} [types] Package types.
33-
* @property {Array.<string>} [cliDependencies] Package cliDependencies.
18+
* @property {string} [name] Package name
19+
* @property {string} [version] Package version
20+
* @property {string} [versionScheme] Package versionScheme
21+
* @property {string} [description] Package description
22+
* @property {string} [author] Package author
23+
* @property {string} [license] Package license
24+
* @property {Package.IRepository} [repository] Package repository
25+
* @property {string} [bugs] Package bugs
26+
* @property {string} [homepage] Package homepage
27+
* @property {Array.<string>} [keywords] Package keywords
28+
* @property {string} [main] Package main
29+
* @property {Object.<string,string>} [bin] Package bin
30+
* @property {Object.<string,string>} [scripts] Package scripts
31+
* @property {Object.<string,string>} [dependencies] Package dependencies
32+
* @property {Object.<string,string>} [devDependencies] Package devDependencies
33+
* @property {string} [types] Package types
34+
* @property {Array.<string>} [cliDependencies] Package cliDependencies
3435
*/
3536

3637
/**
3738
* Constructs a new Package.
3839
* @exports Package
39-
* @classdesc Represents a Package
40+
* @classdesc Represents a Package.
4041
* @constructor
4142
* @param {IPackage=} [properties] Properties to set
4243
*/
@@ -609,15 +610,16 @@ $root.Package = (function() {
609610

610611
/**
611612
* Properties of a Repository.
612-
* @interface Package.IRepository
613-
* @property {string} [type] Repository type.
614-
* @property {string} [url] Repository url.
613+
* @memberof Package
614+
* @interface IRepository
615+
* @property {string} [type] Repository type
616+
* @property {string} [url] Repository url
615617
*/
616618

617619
/**
618620
* Constructs a new Repository.
619-
* @exports Package.Repository
620-
* @classdesc Represents a Repository
621+
* @memberof Package
622+
* @classdesc Represents a Repository.
621623
* @constructor
622624
* @param {Package.IRepository=} [properties] Properties to set
623625
*/

0 commit comments

Comments
 (0)