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