Skip to content

Commit

Permalink
CLI: Various improvements to statically generated JSDoc, also fixes #772
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcodeIO
dcodeIO committed Apr 21, 2017
1 parent 03194c2 commit 13bf9c2
Show file tree
Hide file tree
Showing 9 changed files with 561 additions and 475 deletions.
39 changes: 24 additions & 15 deletions cli/targets/static.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,11 @@ function static_target(root, options, callback) {
push("");
}
if (config.comments) {
if (root.comment)
if (root.comment) {
pushComment("@fileoverview " + root.comment);
else
push("// Exported root namespace");
push("");
}
push("// Exported root namespace");
}
var rootProp = cliUtil.safeProp(config.root || "default");
push((config.es6 ? "const" : "var") + " $root = $protobuf.roots" + rootProp + " || ($protobuf.roots" + rootProp + " = {});");
Expand Down Expand Up @@ -80,13 +81,18 @@ function pushComment(lines) {
}

function exportName(object, asInterface) {
if (asInterface) {
if (object.__interfaceName)
return object.__interfaceName;
} else if (object.__exportName)
return object.__exportName;
var parts = object.fullName.substring(1).split("."),
i = 0;
while (i < parts.length)
parts[i] = escapeName(parts[i++]);
if (asInterface)
parts[i - 1] = "I" + parts[i - 1];
return parts.join(".");
return object[asInterface ? "__interfaceName" : "__exportName"] = parts.join(".");
}

function escapeName(name) {
Expand Down Expand Up @@ -121,7 +127,7 @@ function buildNamespace(ref, ns) {
push("");
pushComment([
ns.comment || "Namespace " + ns.name + ".",
"@exports " + exportName(ns),
ns.parent instanceof protobuf.Root ? "@exports " + escapeName(ns.name) : "@memberof " + exportName(ns.parent),
"@namespace"
]);
push((config.es6 ? "const" : "var") + " " + escapeName(ns.name) + " = {};");
Expand Down Expand Up @@ -352,12 +358,13 @@ function buildType(ref, type) {
if (config.comments) {
var typeDef = [
"Properties of " + aOrAn(type.name) + ".",
"@interface " + exportName(type, true)
type.parent instanceof protobuf.Root ? "@exports " + escapeName("I" + type.name) : "@memberof " + exportName(type.parent),
"@interface " + escapeName("I" + type.name)
];
type.fieldsArray.forEach(function(field) {
var prop = util.safeProp(field.name);
prop = prop.substring(1, prop.charAt(0) === "[" ? prop.length - 1 : prop.length);
typeDef.push("@property {" + toJsType(field) + "} " + (field.optional ? "[" + prop + "]" : field.name) + " " + (field.comment || type.name + " " + field.name + "."));
typeDef.push("@property {" + toJsType(field) + "} " + (field.optional ? "[" + prop + "]" : field.name) + " " + (field.comment || type.name + " " + field.name));
});
push("");
pushComment(typeDef);
Expand All @@ -367,8 +374,8 @@ function buildType(ref, type) {
push("");
pushComment([
"Constructs a new " + type.name + ".",
"@exports " + exportName(type),
"@classdesc " + (type.comment || "Represents " + aOrAn(type.name)),
type.parent instanceof protobuf.Root ? "@exports " + escapeName(type.name) : "@memberof " + exportName(type.parent),
"@classdesc " + (type.comment || "Represents " + aOrAn(type.name) + "."),
"@constructor",
"@param {" + exportName(type, true) + "=} [" + (config.beautify ? "properties" : "p") + "] Properties to set"
]);
Expand Down Expand Up @@ -552,7 +559,7 @@ function buildService(ref, service) {
push("");
pushComment([
"Constructs a new " + service.name + " service.",
"@exports " + exportName(service),
service.parent instanceof protobuf.Root ? "@exports " + escapeName(service.name) : "@memberof " + exportName(service.parent),
"@classdesc " + (service.comment || "Represents " + aOrAn(service.name)),
"@extends $protobuf.rpc.Service",
"@constructor",
Expand Down Expand Up @@ -586,12 +593,13 @@ function buildService(ref, service) {

service.methodsArray.forEach(function(method) {
method.resolve();
var lcName = method.name.substring(0, 1).toLowerCase() + method.name.substring(1);
var lcName = protobuf.util.lcFirst(method.name),
cbName = escapeName(method.name + "Callback");
push("");
var cbName = escapeName(service.name) + "_" + escapeName(lcName) + "_Callback";
pushComment([
"Callback as used by {@link " + escapeName(service.name) + "#" + escapeName(lcName) + "}.",
"Callback as used by {@link " + exportName(service) + "#" + escapeName(lcName) + "}.",
// This is a more specialized version of protobuf.rpc.ServiceCallback
"@memberof " + exportName(service),
"@typedef " + cbName,
"@type {function}",
"@param {Error|null} error Error, if any",
Expand All @@ -601,7 +609,7 @@ function buildService(ref, service) {
pushComment([
method.comment || "Calls " + method.name + ".",
"@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
"@param {" + cbName + "} callback Node-style callback called with the error, if any, and " + method.resolvedResponseType.name,
"@param {" + exportName(service) + "." + cbName + "} callback Node-style callback called with the error, if any, and " + method.resolvedResponseType.name,
"@returns {undefined}"
]);
push(escapeName(service.name) + ".prototype" + util.safeProp(lcName) + " = function " + escapeName(lcName) + "(request, callback) {");
Expand All @@ -613,7 +621,8 @@ function buildService(ref, service) {
push("");
pushComment([
method.comment || "Calls " + method.name + ".",
"@function " + escapeName(service.name) + "#" + lcName,
"@memberof " + exportName(service) + ".prototype",
"@function " + lcName,
"@param {" + exportName(method.resolvedRequestType, !config.forceMessage) + "} request " + method.resolvedRequestType.name + " message or plain object",
"@returns {Promise<" + exportName(method.resolvedResponseType) + ">} Promise",
"@variation 2"
Expand Down
6 changes: 4 additions & 2 deletions tests/data/comments.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,10 @@ $root.Test1 = (function() {

/**
* Properties of a Test1.
* @exports ITest1
* @interface ITest1
* @property {string} [field1] Field with a comment.
* @property {number} [field2] Test1 field2.
* @property {number} [field2] Test1 field2
* @property {boolean} [field3] Field with a comment and a <a href="http://example.com/foo/">link</a>
*/

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

/**
* Properties of a Test2.
* @exports ITest2
* @interface ITest2
*/

/**
* Constructs a new Test2.
* @exports Test2
* @classdesc Represents a Test2
* @classdesc Represents a Test2.
* @constructor
* @param {ITest2=} [properties] Properties to set
*/
Expand Down
21 changes: 11 additions & 10 deletions tests/data/convert.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,23 @@ $root.Message = (function() {

/**
* Properties of a Message.
* @exports IMessage
* @interface IMessage
* @property {string} [stringVal] Message stringVal.
* @property {Array.<string>} [stringRepeated] Message stringRepeated.
* @property {number|Long} [uint64Val] Message uint64Val.
* @property {Array.<number|Long>} [uint64Repeated] Message uint64Repeated.
* @property {Uint8Array} [bytesVal] Message bytesVal.
* @property {Array.<Uint8Array>} [bytesRepeated] Message bytesRepeated.
* @property {Message.SomeEnum} [enumVal] Message enumVal.
* @property {Array.<Message.SomeEnum>} [enumRepeated] Message enumRepeated.
* @property {Object.<string,number|Long>} [int64Map] Message int64Map.
* @property {string} [stringVal] Message stringVal
* @property {Array.<string>} [stringRepeated] Message stringRepeated
* @property {number|Long} [uint64Val] Message uint64Val
* @property {Array.<number|Long>} [uint64Repeated] Message uint64Repeated
* @property {Uint8Array} [bytesVal] Message bytesVal
* @property {Array.<Uint8Array>} [bytesRepeated] Message bytesRepeated
* @property {Message.SomeEnum} [enumVal] Message enumVal
* @property {Array.<Message.SomeEnum>} [enumRepeated] Message enumRepeated
* @property {Object.<string,number|Long>} [int64Map] Message int64Map
*/

/**
* Constructs a new Message.
* @exports Message
* @classdesc Represents a Message
* @classdesc Represents a Message.
* @constructor
* @param {IMessage=} [properties] Properties to set
*/
Expand Down
64 changes: 34 additions & 30 deletions tests/data/mapbox/vector_tile.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,15 @@ $root.vector_tile = (function() {

/**
* Properties of a Tile.
* @interface vector_tile.ITile
* @property {Array.<vector_tile.Tile.ILayer>} [layers] Tile layers.
* @memberof vector_tile
* @interface ITile
* @property {Array.<vector_tile.Tile.ILayer>} [layers] Tile layers
*/

/**
* Constructs a new Tile.
* @exports vector_tile.Tile
* @classdesc Represents a Tile
* @memberof vector_tile
* @classdesc Represents a Tile.
* @constructor
* @param {vector_tile.ITile=} [properties] Properties to set
*/
Expand Down Expand Up @@ -213,20 +214,21 @@ $root.vector_tile = (function() {

/**
* Properties of a Value.
* @interface vector_tile.Tile.IValue
* @property {string} [stringValue] Value stringValue.
* @property {number} [floatValue] Value floatValue.
* @property {number} [doubleValue] Value doubleValue.
* @property {number|Long} [intValue] Value intValue.
* @property {number|Long} [uintValue] Value uintValue.
* @property {number|Long} [sintValue] Value sintValue.
* @property {boolean} [boolValue] Value boolValue.
* @memberof vector_tile.Tile
* @interface IValue
* @property {string} [stringValue] Value stringValue
* @property {number} [floatValue] Value floatValue
* @property {number} [doubleValue] Value doubleValue
* @property {number|Long} [intValue] Value intValue
* @property {number|Long} [uintValue] Value uintValue
* @property {number|Long} [sintValue] Value sintValue
* @property {boolean} [boolValue] Value boolValue
*/

/**
* Constructs a new Value.
* @exports vector_tile.Tile.Value
* @classdesc Represents a Value
* @memberof vector_tile.Tile
* @classdesc Represents a Value.
* @constructor
* @param {vector_tile.Tile.IValue=} [properties] Properties to set
*/
Expand Down Expand Up @@ -532,17 +534,18 @@ $root.vector_tile = (function() {

/**
* Properties of a Feature.
* @interface vector_tile.Tile.IFeature
* @property {number|Long} [id] Feature id.
* @property {Array.<number>} [tags] Feature tags.
* @property {vector_tile.Tile.GeomType} [type] Feature type.
* @property {Array.<number>} [geometry] Feature geometry.
* @memberof vector_tile.Tile
* @interface IFeature
* @property {number|Long} [id] Feature id
* @property {Array.<number>} [tags] Feature tags
* @property {vector_tile.Tile.GeomType} [type] Feature type
* @property {Array.<number>} [geometry] Feature geometry
*/

/**
* Constructs a new Feature.
* @exports vector_tile.Tile.Feature
* @classdesc Represents a Feature
* @memberof vector_tile.Tile
* @classdesc Represents a Feature.
* @constructor
* @param {vector_tile.Tile.IFeature=} [properties] Properties to set
*/
Expand Down Expand Up @@ -836,19 +839,20 @@ $root.vector_tile = (function() {

/**
* Properties of a Layer.
* @interface vector_tile.Tile.ILayer
* @property {number} version Layer version.
* @property {string} name Layer name.
* @property {Array.<vector_tile.Tile.IFeature>} [features] Layer features.
* @property {Array.<string>} [keys] Layer keys.
* @property {Array.<vector_tile.Tile.IValue>} [values] Layer values.
* @property {number} [extent] Layer extent.
* @memberof vector_tile.Tile
* @interface ILayer
* @property {number} version Layer version
* @property {string} name Layer name
* @property {Array.<vector_tile.Tile.IFeature>} [features] Layer features
* @property {Array.<string>} [keys] Layer keys
* @property {Array.<vector_tile.Tile.IValue>} [values] Layer values
* @property {number} [extent] Layer extent
*/

/**
* Constructs a new Layer.
* @exports vector_tile.Tile.Layer
* @classdesc Represents a Layer
* @memberof vector_tile.Tile
* @classdesc Represents a Layer.
* @constructor
* @param {vector_tile.Tile.ILayer=} [properties] Properties to set
*/
Expand Down
48 changes: 25 additions & 23 deletions tests/data/package.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,30 +13,31 @@ $root.Package = (function() {

/**
* Properties of a Package.
* @exports IPackage
* @interface IPackage
* @property {string} [name] Package name.
* @property {string} [version] Package version.
* @property {string} [versionScheme] Package versionScheme.
* @property {string} [description] Package description.
* @property {string} [author] Package author.
* @property {string} [license] Package license.
* @property {Package.IRepository} [repository] Package repository.
* @property {string} [bugs] Package bugs.
* @property {string} [homepage] Package homepage.
* @property {Array.<string>} [keywords] Package keywords.
* @property {string} [main] Package main.
* @property {Object.<string,string>} [bin] Package bin.
* @property {Object.<string,string>} [scripts] Package scripts.
* @property {Object.<string,string>} [dependencies] Package dependencies.
* @property {Object.<string,string>} [devDependencies] Package devDependencies.
* @property {string} [types] Package types.
* @property {Array.<string>} [cliDependencies] Package cliDependencies.
* @property {string} [name] Package name
* @property {string} [version] Package version
* @property {string} [versionScheme] Package versionScheme
* @property {string} [description] Package description
* @property {string} [author] Package author
* @property {string} [license] Package license
* @property {Package.IRepository} [repository] Package repository
* @property {string} [bugs] Package bugs
* @property {string} [homepage] Package homepage
* @property {Array.<string>} [keywords] Package keywords
* @property {string} [main] Package main
* @property {Object.<string,string>} [bin] Package bin
* @property {Object.<string,string>} [scripts] Package scripts
* @property {Object.<string,string>} [dependencies] Package dependencies
* @property {Object.<string,string>} [devDependencies] Package devDependencies
* @property {string} [types] Package types
* @property {Array.<string>} [cliDependencies] Package cliDependencies
*/

/**
* Constructs a new Package.
* @exports Package
* @classdesc Represents a Package
* @classdesc Represents a Package.
* @constructor
* @param {IPackage=} [properties] Properties to set
*/
Expand Down Expand Up @@ -609,15 +610,16 @@ $root.Package = (function() {

/**
* Properties of a Repository.
* @interface Package.IRepository
* @property {string} [type] Repository type.
* @property {string} [url] Repository url.
* @memberof Package
* @interface IRepository
* @property {string} [type] Repository type
* @property {string} [url] Repository url
*/

/**
* Constructs a new Repository.
* @exports Package.Repository
* @classdesc Represents a Repository
* @memberof Package
* @classdesc Represents a Repository.
* @constructor
* @param {Package.IRepository=} [properties] Properties to set
*/
Expand Down
Loading

0 comments on commit 13bf9c2

Please sign in to comment.