jsdocs: Fix up uniqueid, vdl.*, and vlog.
Still have to do vtrace.
Change-Id: I7a1202bcc9c163f6aa35ac83f9e135e5909b2a77
diff --git a/src/lib/uniqueid.js b/src/lib/uniqueid.js
index 64e2f51..e424ea8 100644
--- a/src/lib/uniqueid.js
+++ b/src/lib/uniqueid.js
@@ -53,9 +53,9 @@
}
/**
- * Returns true if the given uniqueid.Id is valid.
+ * Returns true iff the given uniqueid.Id is valid.
* @param {module:vanadium.uniqueId.Id} A uniqueId.Id instance.
- * @return {bool} true if the given uniqueId.Id is valid.
+ * @return {boolean} true if the given uniqueId.Id is valid.
* @memberof module:vanadium.uniqueId
*/
function valid(id) {
@@ -99,12 +99,11 @@
/**
* @summary An Id is a likely globally unique identifier.
* @description
- * <p>An Id is a likely globally unique identifier.</p>
* <p>Use [random]{@link module:vanadium.uniqueId.random} to
- * create a new one</p>
- * @property {Uint8array} val 16-byte array
+ * create a new one.</p>
+ * @property {Uint8array} val 16-byte array.
* @name Id
- * @param {Uint8Array} bytes 16-byte array
+ * @param {Uint8Array} bytes 16-byte array.
* @constructor
* @memberof module:vanadium.uniqueId
*/
diff --git a/src/lib/vlog.js b/src/lib/vlog.js
index 7823645..1ba1276 100644
--- a/src/lib/vlog.js
+++ b/src/lib/vlog.js
@@ -14,29 +14,37 @@
var extend = require('xtend');
/**
- * The log levels used to configure the vanadium logger.
* @namespace
+ * @summary Namespace levels defines the log levels used to configure the
+ * vanadium logger.
+ * @description Namespace levels defines the log levels used to configure the
+ * vanadium logger.
* @memberof module:vanadium.vlog
*/
var levels = {
/**
- * No logs are written
+ * No logs are written.
+ * @const
*/
NOLOG: 0,
/**
- * Only errors are written
+ * Only errors are written.
+ * @const
*/
ERROR : 1,
/**
- * Only errors and warnings are written
+ * Only errors and warnings are written.
+ * @const
*/
WARN: 2,
/**
- * Errors, warnings and debug messages are written
+ * Errors, warnings, and debug messages are written.
+ * @const
*/
DEBUG : 3,
/**
- * All logs are written
+ * All logs are written.
+ * @const
*/
INFO : 4
};
@@ -65,32 +73,32 @@
};
/**
- * Logs arguments as errors to the console if log level is error or higher
- * @param {...*} values The values to log
+ * Logs arguments as errors to the console if log level is error or higher.
+ * @param {...*} values The values to log.
*/
Vlog.prototype.error = function() {
this._log(levels.ERROR, arguments);
};
/**
- * Logs arguments as warnings to the console if log level is warning or higher
- * @param {...*} values The values to log
+ * Logs arguments as warnings to the console if log level is warning or higher.
+ * @param {...*} values The values to log.
*/
Vlog.prototype.warn = function() {
this._log(levels.WARN, arguments);
};
/**
- * Logs arguments as logs to the console if log level is debug or higher
- * @param {...*} values The values to log
+ * Logs arguments as logs to the console if log level is debug or higher.
+ * @param {...*} values The values to log.
*/
Vlog.prototype.debug = function() {
this._log(levels.DEBUG, arguments);
};
/**
- * Logs arguments as info to the console if log level is info or higher
- * @param {...*} values The values to log
+ * Logs arguments as info to the console if log level is info or higher.
+ * @param {...*} values The values to log.
*/
Vlog.prototype.info = function() {
this._log(levels.INFO, arguments);
diff --git a/src/naming/doc.js b/src/naming/doc.js
index d6f0e8a..ea6c634 100644
--- a/src/naming/doc.js
+++ b/src/naming/doc.js
@@ -6,7 +6,7 @@
* MountFlag is a bit mask of options to the mount call.
* @name MountFlag
* @constructor
- * @param {integer} bitMask MountFlag bit mask
+ * @param {number} bitMask MountFlag bit mask
* @memberof module:vanadium.naming
*/
@@ -34,7 +34,7 @@
* @param {string} mountedServer.server Server is the OA that's mounted.
* @param {string[]} mountedServer.blessingPatterns Patterns that match the set
* of blessings presented by the server listening on the above object address.
- * @param {integer} mountedServer.deadline deadline before the mount entry
+ * @param {number} mountedServer.deadline deadline before the mount entry
* expires.
* @memberof module:vanadium.naming
*/
@@ -73,4 +73,4 @@
* @param {module:vanadium.naming.MountEntry} globReply.entry
* @param {module:vanadium.naming.GlobError} globReply.error
* @memberof module:vanadium.naming
- */
\ No newline at end of file
+ */
diff --git a/src/naming/namespace.js b/src/naming/namespace.js
index ff07f4d..89d32c8 100644
--- a/src/naming/namespace.js
+++ b/src/naming/namespace.js
@@ -93,7 +93,7 @@
* @param {module:vanadium.context.Context} ctx The rpc context.
* @param {string} name Object name
* @param {string} server Server object address
- * @param {integer} ttl Expiry time for the mount in milliseconds. ttl of zero
+ * @param {number} ttl Expiry time for the mount in milliseconds. ttl of zero
* implies never expire.
* @param {boolean} Optional replaceMount Whether the previous mount should
* be replaced by the new server object address. False by default.
diff --git a/src/security/access/permissions-authorizer.js b/src/security/access/permissions-authorizer.js
index 2ab7bfd..148d40c 100644
--- a/src/security/access/permissions-authorizer.js
+++ b/src/security/access/permissions-authorizer.js
@@ -34,7 +34,7 @@
* @name permissionsAuthorizer
* @param {module:vanadium.security.access.Permissions} perms The set of
* permission to apply.
- * @param {constructor} type The type of tags that this authorizer understands.
+ * @param {function} type The type of tags that this authorizer understands.
* @return {module:vanadium.security.Authorize} An authorizer that applies
* the perms.
*/
diff --git a/src/security/caveat-validator-registry.js b/src/security/caveat-validator-registry.js
index 790c252..47d34c6 100644
--- a/src/security/caveat-validator-registry.js
+++ b/src/security/caveat-validator-registry.js
@@ -54,7 +54,7 @@
* to validate.
* @memberof module:vanadium.security
* @param {*} param Validation-function specific parameter.
- * @throws Error upon failure to validate, does not throw if successful.
+ * @throws {Error} If validation fails.
*/
/**
@@ -80,7 +80,7 @@
* @param {*} caveat The caveat to validate.
* @param {Function} [cb] Callback after validation is complete.
* See security/types.vdl
- * @throws Error Upon failure to validate, does not throw if successful.
+ * @throws {Error} If validation fails.
* @private
*/
CaveatValidatorRegistry.prototype.validate =
diff --git a/src/vdl/big-int.js b/src/vdl/big-int.js
index 8189863..0d5f510 100644
--- a/src/vdl/big-int.js
+++ b/src/vdl/big-int.js
@@ -12,7 +12,7 @@
module.exports = BigInt;
/**
- * BigInt represents an integer value of arbitrary size.
+ * @summary Represents an integer value of arbitrary size.
* @memberof module:vanadium.vdl
* @param {number} sign The sign of the number 1, -1 or 0.
* @param {Uint8Array} uintBytes The backing byte array, in network byte order.
@@ -50,7 +50,7 @@
* Create a BigInt from a native JavaScript number.
* @param {number} val A native JavaScript value.
* @throws {Error} If value cannot be represented as a BigInt.
- * @return {BigInt} The BigInt representation.
+ * @return {modules:vdl.BigInt} The BigInt representation.
*/
BigInt.fromNativeNumber = function(val) {
if (typeof val !== 'number' || Math.round(val) !== val) {
@@ -69,7 +69,7 @@
* Caution: The conversion is not accurate for large numbers, non-integers, and
* non-numerical inputs.
* @param {number} val A native JavaScript value.
- * @return {BigInt} The BigInt representation.
+ * @return {modules:vanadium.vdl.BigInt} The BigInt representation.
*/
BigInt.fromNativeNumberApprox = function(val) {
var floored;
@@ -110,7 +110,7 @@
* Generate a string representation of the BigInt.
* This must have the same output format as the string conversion of normal
* JavaScript integer (for the range of valid JavaScript integers).
- * @return {string} The string representation.
+ * @return {string} The string representation of the BigInt.
*/
BigInt.prototype.toString = function() {
if (this._sign === 0) {
@@ -147,7 +147,9 @@
/**
* Compares BigInt objects.
- * @return {boolean} True if this BigInt is greater than the passed in BigInt.
+ * @param {modules:vanadium.vdl.BigInt} other The BigInt to compare with this
+ * BigInt.
+ * @return {boolean} True if this BigInt is greater than the argument BigInt.
*/
BigInt.prototype.greaterThan = function(other) {
if (this._sign !== other._sign) {
@@ -172,8 +174,10 @@
/**
* Compares BigInt objects.
- * @return {boolean} True if this BigInt is greater than or equal to the passed
- * in BigInt.
+ * @param {modules:vanadium.vdl.BigInt} other The BigInt to compare with this
+ * BigInt.
+ * @return {boolean} True if this BigInt is greater than or equal to
+ * the argument BigInt.
*/
BigInt.prototype.greaterThanEquals = function(other) {
return this.greaterThan(other) || this.equals(other);
@@ -181,8 +185,10 @@
/**
* Subtracts one BigInt from another.
- * @param {BigInt} other The value to subtract from this BigInt.
- * @return {BigInt} Returns a new BigInt equal to this - other.
+ * @param {modules:vanadium.vdl.BigInt} other The BigInt to subtract from this
+ * BigInt.
+ * @return {modules:vanadium.vdl.BigInt} Returns a new BigInt equal to this
+ * minus the argument BigInt.
*/
BigInt.prototype.subtract = function(other) {
if (this._sign === 0) {
@@ -247,8 +253,9 @@
/**
* Adds two BigInts together.
- * @param {BigInt} other The BigInt to add to this BigInt.
- * @return {BigInt} A new BigInt equal to this + other.
+ * @param {modules:vanadium.vdl.BigInt} other The BigInt to add to this BigInt.
+ * @return {modules:vanadium.vdl.BigInt} A new BigInt equal to this plus the
+ * argument BigInt.
*/
BigInt.prototype.add = function(other) {
if (this._sign === 0) {
@@ -301,9 +308,11 @@
};
/**
- * Multiplies BigInts
- * @param {BigInt} other The BigInt to multiply with this BigInt.
- * @return {BigInt} A new BigInt equal to this * other.
+ * Multiplies BigInts.
+ * @param {modules:vanadium.vdl.BigInt} other The BigInt to multiply with this
+ * BigInt.
+ * @return {modules:vanadium.vdl.BigInt} A new BigInt equal to this times the
+ * argument BigInt.
*/
BigInt.prototype.multiply = function(other) {
var total = new BigInt(0, new Uint8Array());
@@ -325,8 +334,10 @@
/**
* Divides BigInts
- * @param {BigInt} divisor The BigInt to use as the divisor.
- * @return {BigInt} a new BigInt equalt to this / divisor.
+ * @param {modules:vanadium.vdl.BigInt} divisor The BigInt to use as the
+ * divisor.
+ * @return {modules:vanadium.vdl.BigInt} a new BigInt equalt to this divided by
+ * the argument BigInt.
*/
BigInt.prototype.divide = function(divisor) {
if (divisor._sign === 0) {
@@ -356,15 +367,17 @@
/**
* Negates the BigInt.
- * @return {BigInt} A new BigInt that is a negated version the BigInt.
+ * @return {modules:vanadium.vdl.BigInt} A new BigInt that is a negated version
+ * this BigInt.
*/
BigInt.prototype.negate = function() {
return new BigInt(-this._sign, this._bytes);
};
/**
- * Takes the absolute value.
- * @return {BigInt} A new BigInt equal to the absolute value of this BigInt.
+ * Returns the absolute value of the BigInt.
+ * @return {modules:vanadium.vdl.BigInt} A new BigInt equal to the absolute
+ * value of this BigInt.
*/
BigInt.prototype.abs = function() {
return new BigInt(Math.abs(this._sign), this._bytes);
@@ -388,8 +401,9 @@
/**
* Performs left shift of an arbitrary amount.
- * @param {amt} The amount to shift in bits.
- * @return {BigInt} A new BigInt that is left shifted by the specified amount.
+ * @param {number} amt The amount to shift in bits.
+ * @return {modules:vanadium.vdl.BigInt} A new BigInt that is left shifted by
+ * the specified amount.
*/
BigInt.prototype.leftShift = function(amt) {
if (this._bytes.length === 0) {
@@ -426,7 +440,7 @@
/**
* Determine if this BigInt is equal to another BigInt.
*
- * @param {BigInt} other The other BigInt to compare.
+ * @param {modules:vanadium.vdl.BigInt} other The other BigInt to compare.
* @return {boolean} true if this BigInt is equal to the other BigInt. false
* otherwise.
*/
@@ -543,8 +557,8 @@
/**
* Get the sign of the value.
* @private
- * @param {number} val input value
- * @return {number} 1, -1, 0 depending on the sign of the input
+ * @param {number} val Input value.
+ * @return {number} 1, -1, or 0 depending on the sign of the input.
*/
function _sign(val) {
if (val > 0) {
diff --git a/src/vdl/canonicalize.js b/src/vdl/canonicalize.js
index 522584b..871ec4e 100644
--- a/src/vdl/canonicalize.js
+++ b/src/vdl/canonicalize.js
@@ -10,6 +10,16 @@
* @private
*/
+/**
+ * @name canonicalize
+ * @summary Namespace canonicalize implements utilities to canonicalize vdl
+ * types for use in encoding and decoding values.
+ * @description Namespace canonicalize implements utilities to canonicalize vdl
+ * types for use in encoding and decoding values.
+ * @namespace
+ * @memberof module:vanadium.vdl
+ */
+
var BigInt = require('./big-int.js');
var Complex = require('./complex.js');
var kind = require('./kind.js');
@@ -44,9 +54,9 @@
* @function
* @name fill
* @memberof module:vanadium.vdl.canonicalize
- * @param {*} inValue The value to convert to the wire format
- * @param {module:vanadium.vdl.Type} t The type of inValue
- * @return {*} The canonical wire format of inValue
+ * @param {*} inValue The value to convert to the wire format.
+ * @param {module:vanadium.vdl.Type} t The type of inValue.
+ * @return {*} The canonical wire format of inValue.
*/
function canonicalizeFill(inValue, t) {
return canonicalizeExternal(inValue, t, true);
@@ -58,16 +68,16 @@
* @function
* @name reduce
* @memberof module:vanadium.vdl.canonicalize
- * @param {*} inValue The value to convert to the in memory format
- * @param {module:vanadium.vdl.Type} t The type of inValue
- * @return {*} The canonical in-format of inValue
+ * @param {*} inValue The value to convert to the in memory format.
+ * @param {module:vanadium.vdl.Type} t The type of inValue.
+ * @return {*} The canonical in-format of inValue.
*/
function canonicalizeReduce(inValue, t) {
return canonicalizeExternal(inValue, t, false);
}
/**
- * Alias for canonicalizeExternal with inValue = undefined
+ * Alias for canonicalizeExternal with inValue = undefined.
* @private
*/
function canonicalizeZero(t, deepWrap) {
@@ -81,10 +91,10 @@
* TODO(alexfandrianto): The performance is on the same order as encode, but it
* would be a good idea to consider adding more improvements.
* @private
- * @param {any} inValue The value to be canonicalized
- * @param {Type} t The target type
+ * @param {*} inValue The value to be canonicalized.
+ * @param {module:vanadium.vdl.Type} t The target type.
* @param {boolean=} deepWrap Whether or not to deeply wrap. Defaults to true.
- * @return {any} The canonicalized value (May potentially refer to v)
+ * @return {*} The canonicalized value. May potentially refer to v.
*/
function canonicalizeExternal(inValue, t, deepWrap) {
if (deepWrap === undefined) {
@@ -101,16 +111,16 @@
* Keeps track of a Map of old references to new references. This helps clone
* cycles and preserve shared references.
* @private
- * @param {any} v The value to be canonicalized
- * @param {Type} inType The inferred type of the value. This type is tracked in
- * order to ensure that internal any keys/elems/fields are
- * properly filled in with type information.
- * @param {Type} t The target type
+ * @param {*} v The value to be canonicalized.
+ * @param {module:vanadium.vdl.Type} inType The inferred type of the value.
+ * This type is tracked in order to ensure that internal any keys/elems/fields
+ * are properly filled in with type information.
+ * @param {module:vanadium.vdl.Type} t The target type.
* @param {boolean} deepWrap Whether or not to deeply wrap the contents.
* @param {object} seen A cache from old to new
* references that based on type.
- * @param {boolean} isTopLevelValue If true, then the return value is wrapped
- * @return {any} The canonicalized value (May potentially refer to v)
+ * @param {boolean} isTopLevelValue If true, then the return value is wrapped.
+ * @return {*} The canonicalized value. May potentially refer to v.
*/
function canonicalize(inValue, inType, t, deepWrap, seen, isTopLevelValue) {
if (!(t instanceof Type)) {
@@ -535,7 +545,7 @@
* zeroValues need further canonicalization, so it would make sense to have it
* be a simple initializer instead of being recursive.
* @param(Type) t The type whose zero value is needed.
- * @return {any} the corresponding zero value for the input type.
+ * @return {*} the corresponding zero value for the input type.
* @private
*/
function zeroValue(t) {
@@ -598,10 +608,10 @@
/**
* Constructs an error for the value, type, and custom message.
- * @param {any} value The value
- * @param {Type} type The type
- * @param {string} message The custom error message
- * @return {Error} The constructed error
+ * @param {*} value The value.
+ * @param {module:vanadium.vdl.Type} type The type.
+ * @param {string} message The custom error message.
+ * @return {Error} The constructed error.
* @private
*/
function makeError(value, type, message) {
@@ -612,9 +622,9 @@
/**
* Examines the given type and canonicalizes it. If the type is not valid for
* its kind, then an error is thrown.
- * @param {Type} t The type to be canonicalized
- * @return {Type} The canonicalized type
- * @throws If the type is invalid
+ * @param {module:vanadium.vdl.Type} t The type to be canonicalized.
+ * @return {module:vanadium.vdl.Type} The canonicalized type.
+ * @throws {Error} If the type is invalid.
* @private
*/
function canonicalizeTypeExternal(t) {
@@ -746,7 +756,7 @@
* @param {type} type The proposed type whose constructor is needed.
* @param {v} value The value that is passed in. If v is a native type,
* its constructor is used instead of looking up in the registry.
- * @return {object} The empty object with correct type
+ * @return {object} The empty object with correct type.
* @private
*/
function getObjectWithType(t, v) {
@@ -766,11 +776,12 @@
}
/**
- * insertIntoSeenCache adds the new reference into the cache.
+ * Adds the new reference into the cache.
* @param {object} seen Cache of old to new refs by type.
- * @param {object} oldRef The old reference
- * @param {Type} type The type the new reference is being cached under.
- * @param {object} newRef The new reference
+ * @param {object} oldRef The old reference.
+ * @param {module:vanadium.vdl.Type} type The type the new reference is being
+ * cached under.
+ * @param {object} newRef The new reference.
* @private
*/
function insertIntoSeenCache(seen, oldRef, type, newRef) {
@@ -781,11 +792,12 @@
}
/**
- * getFromSeenCache returns a cached value from the seen cache.
+ * Returns a cached value from the seen cache.
* If there is no such value, the function returns undefined.
* @param {object} seen Cache of old to new refs by type.
- * @param {object} oldRef The old reference
- * @param {Type} type The type the new reference is being cached under.
+ * @param {object} oldRef The old reference.
+ * @param {module:vanadium.vdl.Type} type The type the new reference is being
+ * cached under.
* @return {object | undefined} The cached value or undefined, if not present.
* @private
*/
@@ -806,7 +818,7 @@
* Ex: wrapped primitive =>
{ unwrappedValue: primitive, guessedType: typeOfPrimitiveWrapper }
* Ex: nativeVal => { unwrappedValue: nativeVal, guessedType: types.JSVALUE }
- * @param{any} v The value which may have nested ANY
+ * @param{*} v The value which may have nested ANY
* @return{object} Object with guessedType => type and unwrappedValue => value
* @private
*/
diff --git a/src/vdl/complex.js b/src/vdl/complex.js
index c69c8c3..97af663 100644
--- a/src/vdl/complex.js
+++ b/src/vdl/complex.js
@@ -3,18 +3,18 @@
// license that can be found in the LICENSE file.
/**
- * @fileoverview A type for complex numbers
+ * @fileoverview A type for complex numbers.
* @private
*/
module.exports = Complex;
/**
- * Represents a complex number
+ * @summary Represents a complex number.
* @constructor
* @memberof module:vanadium.vdl
- * @param {number} real The real part of the number
- * @param {number} imag The imaginary part the number
+ * @param {number} real The real part of the number.
+ * @param {number} imag The imaginary part of the number.
*/
function Complex(real, imag) {
this.real = real || 0;
@@ -22,7 +22,7 @@
}
/**
- * @returns string The string format of the number
+ * @returns {string} The string format of this complex number.
*/
Complex.prototype.toString = function() {
if (this.imag === 0) {
@@ -40,9 +40,11 @@
};
/**
- * Adds c to this
- * @param {module:vanadium.vdl.Complex} c The number to add
- * @returns {module:vanadium.vdl.Complex} this + c
+ * Adds a complex number to this complex number.
+ * @param {module:vanadium.vdl.Complex} c The complex number to add to this
+ * complex number.
+ * @returns {module:vanadium.vdl.Complex} This complex number plus the argument
+ * complex number.
*/
Complex.prototype.add = function(c){
return new Complex(this.real + c.real,
@@ -51,9 +53,11 @@
};
/**
- * Subtracts c from this
- * @param {module:vanadium.vdl.Complex} c The number to subtract
- * @returns {module:vanadium.vdl.Complex} this - c
+ * Subtracts a complex number from this number.
+ * @param {module:vanadium.vdl.Complex} c The complex number to subtract from
+ * this complex number.
+ * @returns {module:vanadium.vdl.Complex} This complex number minus the
+ * argument complex number.
*/
Complex.prototype.subtract = function(c) {
return new Complex(this.real - c.real,
@@ -61,9 +65,11 @@
};
/**
- * Multiply c with this
- * @param {module:vanadium.vdl.Complex} c The number to multiply by
- * @returns {module:vanadium.vdl.Complex} this * c
+ * Multiply a complex number with this number.
+ * @param {module:vanadium.vdl.Complex} c The compler number to multiply this
+ * complex number with.
+ * @returns {module:vanadium.vdl.Complex} This complex number times the
+ * argument complex number.
*/
Complex.prototype.multiply = function(c) {
var real = this.real * c.real -
@@ -74,9 +80,11 @@
};
/**
- * Divde this by c
- * @param {module:vanadium.vdl.Complex} c The number to divide by
- * @returns {module:vanadium.vdl.Complex} this / c
+ * Divide this complex number by another complex number.
+ * @param {module:vanadium.vdl.Complex} c The complex number to divide this
+ * complex number by.
+ * @returns {module:vanadium.vdl.Complex} This complex number divided by the
+ * argument complex number.
*/
Complex.prototype.divide = function(c) {
var num = this.multiply(new Complex(c.real, -c.imag));
diff --git a/src/vdl/doc.js b/src/vdl/doc.js
index b26b39d..4ce09de 100644
--- a/src/vdl/doc.js
+++ b/src/vdl/doc.js
@@ -3,57 +3,57 @@
// license that can be found in the LICENSE file.
/**
- * Interface describes the signature of an interface.
* @constructor
* @name Interface
- * @property {string} name
- * @property {string} pkgPath
- * @property {string} doc
+ * @summary Describes the signature of an interface.
+ * @property {string} name Name of the interface.
+ * @property {string} pkgPath Path of the interface.
+ * @property {string} doc Documentation for the interface.
* @property {module:vanadium.vdl.signature.Embed[]} embeds No special ordering.
- * @property {module:vanadium.vdl.signature.Method[]} method Ordered by method
+ * @property {module:vanadium.vdl.signature.Method[]} method Ordered by method.
* name.
* @memberof module:vanadium.vdl.signature
*/
/**
- * Embed describes the signature of an embedded interface.
* @constructor
* @name Embed
- * @property {string} name
- * @property {string} pkgPath
- * @property {string} doc
+ * @summary Describes the signature of an embedded interface.
+ * @property {string} name Name of the embedded interface.
+ * @property {string} pkgPath Path of the embedded interface.
+ * @property {string} doc Documentation for the embedded interface.
* @memberof module:vanadium.vdl.signature
*/
/**
- * Method describes the signature of an interface method.
* @constructor
* @name Method
+ * @summary Describes the signature of an interface method.
* @property {string} Name
* @property {string} PkgPath
- * @property {module:vanadium.vdl.signature.Arg[]} inArgs Input arguments
- * @property {module:vanadium.vdl.signature.Arg[]} outArgs Output arguments
- * @property {module:vanadium.vdl.signature.Arg} inStream Input stream
+ * @property {module:vanadium.vdl.signature.Arg[]} inArgs Input arguments.
+ * @property {module:vanadium.vdl.signature.Arg[]} outArgs Output arguments.
+ * @property {module:vanadium.vdl.signature.Arg} inStream Input stream.
* (optional)
- * @property {module:vanadium.vdl.signature.Arg} outStream Output stream
+ * @property {module:vanadium.vdl.signature.Arg} outStream Output stream.
* (optional)
- * @property {*} tags Method tags
+ * @property {*} tags Method tags.
* @memberof module:vanadium.vdl.signature
*/
/**
- * Arg describes the signature of a single argument.
* @constructor
* @name Arg
- * @property {string} name
- * @property {string} doc
- * @property {module:vanadium.vdl.Type} type
+ * @summary Describes the signature of a single argument.
+ * @property {string} name Name of the argument.
+ * @property {string} doc Documentation for the argument.
+ * @property {module:vanadium.vdl.Type} type Type of the argument.
* @memberof module:vanadium.vdl.signature
*/
/**
- * Duration represents the elapsed duration between two points in time,
- * with up to nanosecond precision.
* @constructor
* @name Duration
- * @property seconds {integer} Seconds represents the seconds in the duration.
- * @property nanos {integer} In normalized form, durations less than one second
+ * @summary Represents the elapsed duration between two points in time, with up
+ * to nanosecond precision.
+ * @property seconds {number} Seconds represents the seconds in the duration.
+ * @property nanos {number} In normalized form, durations less than one second
* are represented with 0. Seconds and +/-Nanos. For durations one second or
* more, the sign of Nanos must match Seconds, or be 0.
* @memberof module:vanadium.vdl.time
diff --git a/src/vdl/guess-type.js b/src/vdl/guess-type.js
index 493d288..5e6661f 100644
--- a/src/vdl/guess-type.js
+++ b/src/vdl/guess-type.js
@@ -20,8 +20,8 @@
* Guess the type of a value based on its contents. If _type is not present
* this returns types.JSValue.
* @private
- * @param {any} val The value.
- * @return {Type} The guessed type for val.
+ * @param {*} val The value.
+ * @return {module:vanadium.vdl.Type} The guessed type for val.
*/
function guessType(val) {
if (typeUtil.isTyped(val)) {
diff --git a/src/vdl/index.js b/src/vdl/index.js
index 56707e8..dd95cc7 100644
--- a/src/vdl/index.js
+++ b/src/vdl/index.js
@@ -11,11 +11,13 @@
* system.</p>
*
* <p>VDL is an interface definition language designed to enable interoperation
- * between clients and servers executing in heterogeneous environments. E.g. it
- * enables a frontend written in Javascript running on a phone to communicate
- * with a backend written in Go running on a server. VDL is compiled into an
- * intermediate representation that is used to generate code in each target
- * environment.</p>
+ * between clients and servers executing in heterogeneous environments.</p>
+ *
+ * For example, VDL enables a frontend written in Javascript running on a phone
+ * to communicate with a backend written in Go running on a server.</p>
+ *
+ * <p>VDL is compiled into an intermediate representation that is used to
+ * generate code in each target environment.</p>
*
* <p>The concepts in VDL are similar to the concepts used in general-purpose
* languages to specify interfaces and communication protocols.</p>
@@ -28,18 +30,11 @@
kind: require('./kind'),
types: require('./types'),
BigInt: require('./big-int'),
- /**
- * Namespace of utilities to canonicalize vdl types
- * for use in encoding and decoding values.
- * @namespace
- * @memberof module:vanadium.vdl
- */
canonicalize: require('./canonicalize'),
Complex: require('./complex'),
/**
* Type registry that contains a mapping of vdl types
* to constructors
- * @property {module:vanadium.vdl~Registry}
* @memberof module:vanadium.vdl
*/
registry: require('./registry'),
@@ -49,12 +44,16 @@
/**
* @namespace
* @name signature
+ * @summary Namespace of types representing interface and method signatures.
+ * @description Namespace of types representing interface and method signatures.
* @memberof module:vanadium.vdl
*/
module.exports.signature = require('../gen-vdl/v.io/v23/vdlroot/signature');
/**
* @namespace
* @name time
+ * @summary Namespace of types representing absolute and relative times.
+ * @description Namespace of types representing absolute and relative times.
* @memberof module:vanadium.vdl
*/
module.exports.time = require('../gen-vdl/v.io/v23/vdlroot/time');
diff --git a/src/vdl/js-value-convert.js b/src/vdl/js-value-convert.js
index fc94f12..aef81f4 100644
--- a/src/vdl/js-value-convert.js
+++ b/src/vdl/js-value-convert.js
@@ -42,8 +42,8 @@
* Excluding undefined, raw values satisfy the following equality:
* convertToNative(convertFromNative(val)) === val
* @private
- * @param{any} val The value to be molded into a JSValue
- * @return The JSValue
+ * @param {*} val The value to be molded into a JSValue.
+ * @return {*} The JSValue.
*/
function convertFromNative(val) {
// No need to convert if val is already a JSValue or typed object.
diff --git a/src/vdl/kind.js b/src/vdl/kind.js
index 8b78f4f..beb369f 100644
--- a/src/vdl/kind.js
+++ b/src/vdl/kind.js
@@ -10,7 +10,8 @@
var kindCount = 0;
/**
- * Namespace of constants for VDL kinds
+ * @summary Namespace of constants for VDL kinds.
+ * @description Namespace of constants for VDL kinds.
* @namespace
* @memberof module:vanadium.vdl
*/
@@ -114,9 +115,9 @@
};
/**
- * Returns the human readable name for a kind
- * @param {module:vanadium.vdl.kind} k The kind to print out
- * @return {string}
+ * Returns the human-readable name for a kind.
+ * @param {module:vanadium.vdl.kind} k The kind to print out.
+ * @return {string} Human-readable name for the kind.
*/
kind.kindStr = function(k) {
var kindKeys = Object.keys(kind).filter(function(key) {
diff --git a/src/vdl/native-type-registry.js b/src/vdl/native-type-registry.js
index a1de500..fa833e7 100644
--- a/src/vdl/native-type-registry.js
+++ b/src/vdl/native-type-registry.js
@@ -40,7 +40,7 @@
/**
* Registers a converter that converts from native type to wire type.
* @private
- * @param {constructor} constructor The constructor for the native object.
+ * @param {function} constructor The constructor for the native object.
* @param {function} f A function that takes in a native object and returns
* the wire type representation of it.
* @param {Type} type The wiretype fo the native value.
diff --git a/src/vdl/registry.js b/src/vdl/registry.js
index 73e430e..68ee5ab 100644
--- a/src/vdl/registry.js
+++ b/src/vdl/registry.js
@@ -9,9 +9,12 @@
require('./es6-shim');
/**
- * The Registry maps types to corresponding constructors.
- * These constructors convert a given value to a a vom-typed object.
- * There is no support for removing added constructors.<br>
+ * @summary Maps types to corresponding constructors.
+ *
+ * @description
+ * <p>Registered constructors convert a given value to a a vom-typed object.
+ * There is no support for removing added constructors.</p>
+ *
* @constructor
* @inner
* @memberof module:vanadium.vdl
@@ -65,8 +68,10 @@
};
/**
- * Lookup a constructor or if it isn't found, create a new one and register it.
+ * Lookup a constructor. If it isn't found, then create a new one and register
+ * it.
* @param {module:vanadium.vdl.Type} type Type
+ * @return {function} The constructor function for the type.
*/
Registry.prototype.lookupOrCreateConstructor = function(type) {
if (!(type instanceof Type)) {
diff --git a/src/vdl/type-util.js b/src/vdl/type-util.js
index 24e439c..242a930 100644
--- a/src/vdl/type-util.js
+++ b/src/vdl/type-util.js
@@ -23,7 +23,7 @@
* Determines if the length should be sent in the header of a value message of
* the specified type.
* @private
- * @param {Type} type The type.
+ * @param {module:vanadium.vdl.Type} type The type.
* @return {boolean} true if the length should be sent in the header of the
* the value message or false otherwise.
*/
@@ -53,7 +53,7 @@
/**
* Checks whether the given value is a typed value.
* @private
- * @param {any} v The potentially typed value.
+ * @param {*} v The potentially typed value.
* @return {boolean} whether the value has a type attached or not.
*/
function isTyped(v) {
@@ -75,7 +75,7 @@
* Note: The convention is to only wrap types once, not deeply.
* @private
* @param {VomValue} v The value to be unwrapped.
- * @return {any} the unwrapped value.
+ * @return {*} the unwrapped value.
*/
function unwrap(v) {
if (isWrapped(v)) {
@@ -106,7 +106,7 @@
* Unwrap the value if the unwrapped type will be guessed on encode.
* @private
* @param {VomValue} v The value to be unwrapped.
- * @return {any} the unwrapped value.
+ * @return {*} the unwrapped value.
*/
function unwrapNonDefault(v) {
// TODO(bprosnitz) This function doesn't match the default guess rules.
diff --git a/src/vdl/type.js b/src/vdl/type.js
index 9fd90f1..497003e 100644
--- a/src/vdl/type.js
+++ b/src/vdl/type.js
@@ -16,14 +16,16 @@
var canonicalize; // Must be lazily-required to avoid circular dependency.
/**
- * Creates a new Type.
- * Without o, the Type is incomplete and must be filled in further.
- * Notably, each type has a kind, which implies the existence of other fields.
- * Type can be optionally constructed with an object, which has the option of
- * being canonicalized.
- * Note: Sidesteps a cyclic dependency with injection. During module setup,
- * any calls to the Type constructor with a type object should also set
- * skipValidation to true.
+ * @summary Creates a new Type.
+ *
+ * @description <p>Without o, the Type is incomplete and must be filled in
+ * further.</p>
+ * <p>Notably, each type has a kind, which implies the existence of other
+ * fields. Type can be optionally constructed with an object, which has the
+ * option of being canonicalized.</p>
+ * <p>Note: This sidesteps a cyclic dependency with injection. During module
+ * setup, any calls to the Type constructor with a type object should also set
+ * skipValidation to true.</p>
* @constructor
* @memberof module:vanadium.vdl
* @param {Object=} o An object whose fields match those of a TypeObject.
@@ -52,8 +54,8 @@
/**
* Checks for equality
- * @param {*} other The value to test against
- * @return boolean True iff other equals this.
+ * @param {*} other The value to check for equality against.
+ * @return {boolean} True iff other equals this.
*/
Type.prototype.equals = function(other) {
if (this === other) {
@@ -79,6 +81,7 @@
};
/**
+ * Get a human-readable string for this type.
* @return {string} The human-readable string for this type
*/
Type.prototype.toString = function() {
@@ -89,8 +92,9 @@
};
/**
- * Compute a unique type string that breaks cycles.
- * Note: This logic replicates that of uniqueTypeStr in type_builder.go
+ * <p>Compute a unique type string that breaks cycles.</p>
+ *
+ * <p>Note: This logic replicates that of uniqueTypeStr in type_builder.go.</p>
* @private
* @param {Type} t The type whose unique type string is needed
* @param {Array} seen A list of seen type references
diff --git a/src/vdl/types.js b/src/vdl/types.js
index 28e7cf5..23f216e 100644
--- a/src/vdl/types.js
+++ b/src/vdl/types.js
@@ -14,7 +14,8 @@
// create the types in js?
/**
- * Namespace of pre-defined VDL Types
+ * @summary Namespace of pre-defined VDL Types.
+ * @description Namespace of pre-defined VDL Types.
* @namespace
* @memberof module:vanadium.vdl
*/
diff --git a/src/vdl/util.js b/src/vdl/util.js
index b759c4c..540dd2d 100644
--- a/src/vdl/util.js
+++ b/src/vdl/util.js
@@ -39,7 +39,7 @@
* Note: Strings starting with a special character are considered capitalized.
* @private
* @param {string} s The string.
- * @return {bool} whether or not the string is capitalized.
+ * @return {boolean} whether or not the string is capitalized.
*/
function isCapitalized(s) {
return s[0].toUpperCase() === s[0];
@@ -49,7 +49,7 @@
* Returns true if the field doesn't start with '_'.
* @param {string} field The field label of a struct.
* @private
- * @return {bool} whether or not the field should be exported.
+ * @return {boolean} whether or not the field should be exported.
*/
function isExportedStructField(field) {
return field.length > 0 && field[0] !== '_';
diff --git a/src/verror/make-errors.js b/src/verror/make-errors.js
index cbae09a..7eb47ea 100644
--- a/src/verror/make-errors.js
+++ b/src/verror/make-errors.js
@@ -20,10 +20,9 @@
* otherwise it is a map from languageId to format string.
* @param {Array} types The array of types that expected for the arguments to
* the error constructor.
- * @returns {function} A constructor function
- * that can be used to create vanadium errors with the given error id.
- * The returned constructor function inherits from
- * {@link module:vanadium.verror.VanadiumError}.
+ * @returns {function} A constructor function that can be used to create
+ * vanadium errors with the given error id. The returned constructor function
+ * inherits from {@link module:vanadium.verror.VanadiumError}.
* @memberof module:vanadium.verror
*/
function makeError(id, retryCode, format, types) {
@@ -58,4 +57,4 @@
}
}
return Errors[fname];
-}
\ No newline at end of file
+}
diff --git a/src/vom/type-decoder.js b/src/vom/type-decoder.js
index fb4592b..d3fb503 100644
--- a/src/vom/type-decoder.js
+++ b/src/vom/type-decoder.js
@@ -98,7 +98,8 @@
/**
* Flattens the type's dependencies into a typeId->(type, partial type) map.
- * @throws Error if the type's dependencies are not available.
+ * @private
+ * @throws {Error} If the type's dependencies are not available.
*/
TypeDecoder.prototype._flattenTypeDepGraph = function(typeId, typeDeps) {
// Already in map?
diff --git a/src/vtrace/doc.js b/src/vtrace/doc.js
index e2ff9ad..6f131f9 100644
--- a/src/vtrace/doc.js
+++ b/src/vtrace/doc.js
@@ -41,7 +41,7 @@
* @summary TraceFlags specify options for how traces should be collected.
* @name TraceFlags
* @constructor
- * @param {integer} flag
+ * @param {number} flag
* @memberof module:vanadium.vtrace
*/
