core.js: Fixing context and error docs.
Change-Id: I03e91fe840101d1033e8a2a782afa07eabdede3a
diff --git a/jsdocs/index.md b/jsdocs/index.md
index 429b06f..3050198 100644
--- a/jsdocs/index.md
+++ b/jsdocs/index.md
@@ -1,7 +1,7 @@
##Vanadium JavaScript API
-Vanadium provides JavaScript APIs into its application environment to enable development of Vanadium-based applications in JavaScript. These applications currently work in NodeJS and in the desktop Chrome browser.
+Vanadium is an ongoing effort to build an open source, cross-platform application framework for secure, cross-device user experiences. For more details about the Vanadium project, please visit [https://v.io](https://v.io).
-For more details about the Vanadium project, please visit [https://v.io](https://v.io).
+[Vanadium module](./module-vanadium.html) provides JavaScript APIs into its application environment to enable development of Vanadium-based applications in JavaScript. These applications currently work in NodeJS and in the desktop Chrome browser.
##[Vanadium Module](./module-vanadium.html)
[Vanadium module](./module-vanadium.html) is the entry point to the public Vanadium API.
diff --git a/src/browser/extension-errors.js b/src/browser/extension-errors.js
index cf0ffbc..56757f8 100644
--- a/src/browser/extension-errors.js
+++ b/src/browser/extension-errors.js
@@ -12,6 +12,7 @@
};
/**
+ * @summary
* ExtensionCrashError indicates that the Vanadium extension has crashed.
* This is only available in browser environment and will not exist in NodeJS.
* @name ExtensionCrashError
@@ -29,8 +30,10 @@
inherits(ExtensionCrashError, Error);
/**
+ * @summary
* ExtensionNotInstalledError indicates that the Vanadium extension is not
* installed.
+ * @description
* This is only available in browser environment and will not exist in NodeJS.
* @name ExtensionNotInstalledError
* @constructor
diff --git a/src/context/index.js b/src/context/index.js
index a89f7e4..3dcfac7 100644
--- a/src/context/index.js
+++ b/src/context/index.js
@@ -19,7 +19,7 @@
* vanadium.init(function(err, runtime) {
* var ctx = runtime.getContext();
* doSomething(ctx);
- * });
+ * });
* </pre>
* </li>
* <li>The first parameter to every Vanadium server method implementation
@@ -35,7 +35,7 @@
* </ol></p>
*
* <p>Once you have a context you can derive further contexts to
- * change settings. for example to adjust a deadline you might do:
+ * change settings. For example to adjust a deadline you might do:
* </p>
* <pre>
* vanadium.init(function(err, runtime) {
@@ -108,7 +108,8 @@
* boundaries.
* @description
* Generally application code should not call this constructor to
- * create contexts. Instead it should call runtime.getContext() or
+ * create contexts. Instead it should call
+ * [runtime.getContext]{@link module:vanadium~Runtime#getContext} or
* use the context supplied as the first argument to server method
* implementations.
* @constructor
@@ -123,7 +124,7 @@
/**
* Returns the time at which this context will be automatically
* canceled. If no deadline has been set, null is returned.
- * @return {Date} The Date corresponding to the deadline
+ * @return {Date} The Date corresponding to the deadline.
*/
Context.prototype.deadline = function() {
return null;
@@ -133,21 +134,38 @@
/**
* Returns true if the context has exceeded its deadline,
* been cancelled, or been finished.
- * @return {boolean} True if the context is done
+ * @return {boolean} True if the context is done.
*/
Context.prototype.done = function() {
return false;
};
+/**
+ * Frees resources associated with the context without generating an error.
+ * Only applicable to context objects returned from withCancel(). It does
+ * nothing for other contexts.
+ */
Context.prototype.finish = function() {
// Do nothing for most contexts.
};
/**
+ * Can be used to cancel the context and generate a
+ * {@link module:vanadium.verror.CanceledError}.
+ * Only applicable to context objects returned from withCancel(). It does
+ * nothing for other contexts.
+ */
+Context.prototype.cancel = function() {
+ // Do nothing for most contexts.
+};
+
+/**
* Returns a promise that will be resolved when the context exceeds
* its deadline, is cancelled, or is finished. Optionally you can
* pass a callback that will be run when the promise is resolved.
- * @param {function} cb A callback function(error) to call upon cancellation
+ * @param {module:vanadium~voidCb} [cb] If provided, the function
+ * will be called on completion.
+ * @return {Promise} Promise to be called on completion.
*/
Context.prototype.waitUntilDone = function(callback) {
// The root context can never be cancelled, and therefore we
@@ -166,8 +184,8 @@
* just to pass extra parameters to functions and methods. The key
* must be an instance of ContextKey. This function will return null
* if there is no value associated with the given key.
- * @param {module:vanadium.context.ContextKey} A ContextKey to look up
- * @return {*} The value associated with the key, or null
+ * @param {module:vanadium.context.ContextKey} key A ContextKey to look up.
+ * @return {*} The value associated with the key, or null.
*/
Context.prototype.value = function(key) {
return null;
@@ -188,9 +206,11 @@
/**
* Returns a new context derived from the current context but that can
* be cancelled. The returned context will have two additional
- * methods cancel() which can be used to cancel the context and
- * generate a module:vanadium.verror.CanceledError and finish() which frees
- * resources associated with the context without generating an error.
+ * methods [cancel()]{@link module:vanadium.context.Context#cancel} which
+ * can be used to cancel the context and
+ * generate a {@link module:vanadium.verror.CanceledError} and
+ * [finish()]{@link module:vanadium.context.Context#finish} which
+ * frees resources associated with the context without generating an error.
* @return {module:vanadium.context.Context} A new derived cancellable context.
*/
Context.prototype.withCancel = function() {
diff --git a/src/naming/doc.js b/src/naming/doc.js
index b76db89..d6f0e8a 100644
--- a/src/naming/doc.js
+++ b/src/naming/doc.js
@@ -59,7 +59,7 @@
* @constructor
* @param {Object} globError
* @param {string} globError.name Name Root of the subtree.
- * @param {module.vanadium.errors.VanadiumError} globError.error The error that
+ * @param {module.vanadium.verror.VanadiumError} globError.error The error that
* occurred fulfilling the request.
* @memberof module:vanadium.naming
*/
diff --git a/src/rpc/server.js b/src/rpc/server.js
index 0647298..31a694e 100644
--- a/src/rpc/server.js
+++ b/src/rpc/server.js
@@ -65,12 +65,6 @@
*/
/**
- * Void callback is an callback that will be called on completion of an
- * async operation that has no results
- * @callback module:vanadium.rpc~Server~voidCb
- * @param {error} err If set, the error that occurred.
- */
-/**
* <p>Serve associates object with name by publishing the address
* of this server with the mount table under the supplied name and using
* authorizer to authorize access to it.</p>
@@ -93,7 +87,7 @@
* @param {object} serviceObject The service object that has a set of
* exported methods
* @param {module:vanadium.rpc~Server~ServeOptions} options Options config
- * @param {module:vanadium.rpc~Server~voidCb} [cb] If provided, the function
+ * @param {module:vanadium~voidCb} [cb] If provided, the function
* will be called on completion.
* @return {Promise} Promise to be called when serve completes or fails.
*/
@@ -170,7 +164,7 @@
* @param {module:vanadium.rpc~Dispatcher} dispatcher A function that will
* take in the suffix and the method to be called and return the service
* object for that suffix.
- * @param {module:vanadium.rpc~Server~voidCb} [cb] If provided, the function
+ * @param {module:vanadium~voidCb} [cb] If provided, the function
* will be called on completion.
* @return {Promise} Promise to be called when serve completes or fails.
*/
@@ -183,7 +177,7 @@
* Stop gracefully stops all services on this Server.
* New calls are rejected, but any in-flight calls are allowed to complete.
* All published named are unmounted.
- * @param {module:vanadium.rpc~Server~voidCb} [cb] If provided, the function
+ * @param {module:vanadium~voidCb} [cb] If provided, the function
* will be called on completion.
* @return {Promise} Promise to be called when stop service completes or fails
*/
@@ -200,7 +194,7 @@
* or [addName]{@link module:vanadium.rpc~Server#addName}.
* @public
* @param {string} name Name to publish
- * @param {module:vanadium.rpc~Server~voidCb} [cb] If provided, the function
+ * @param {module:vanadium~voidCb} [cb] If provided, the function
* will be called on completion.
* @return {Promise} Promise to be called when operation completes or fails
*/
diff --git a/src/vanadium.js b/src/vanadium.js
index c81649a..865f8f9 100644
--- a/src/vanadium.js
+++ b/src/vanadium.js
@@ -58,6 +58,12 @@
module.exports.extension = require('./browser/extension-utils');
}
/**
+ * Void callback is an callback that will be called on completion of an
+ * async operation that has no results
+ * @callback module:vanadium~voidCb
+ * @param {Error} err If set, the error that occurred.
+ */
+/**
* Callback passed into the {@link module:vanadium.init} that will be
* called when the initialization has finished.
* @callback module:vanadium~runtimeCb
diff --git a/src/verror/actions.js b/src/verror/actions.js
index 1c7029c..8b93dd0 100644
--- a/src/verror/actions.js
+++ b/src/verror/actions.js
@@ -2,9 +2,35 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+/**
+ * Represents the action expected to be performed by a typical client receiving
+ * an error that perhaps it does not understand.
+ * @namespace actions
+ * @memberof module:vanadium.verror
+ */
module.exports = {
+ /**
+ * Do not retry.
+ * @const
+ * @memberof module:vanadium.verror.actions
+ */
NO_RETRY: 'NoRetry',
+ /**
+ * Renew high-level connection/context.
+ * @const
+ * @memberof module:vanadium.verror.actions
+ */
RETRY_CONNECTION: 'RetryConnection',
+ /**
+ * Refetch and retry (e.g., out of date HTTP ETag).
+ * @const
+ * @memberof module:vanadium.verror.actions
+ */
RETRY_REFETCH: 'RetryRefetch',
+ /**
+ * Backoff and retry a finite number of times.
+ * @const
+ * @memberof module:vanadium.verror.actions
+ */
RETRY_BACKOFF: 'RetryBackoff'
-};
+};
\ No newline at end of file
diff --git a/src/verror/docs.js b/src/verror/docs.js
index 7781cbd..8d4c3eb 100644
--- a/src/verror/docs.js
+++ b/src/verror/docs.js
@@ -9,7 +9,10 @@
* to be kept up to date with the vdl file.
*/
/**
- * UnknownError means the error has no known Id. A more specific error should
+ * @summary
+ * UnknownError means the error has no known Id.
+ * @description
+ * A more specific error should
* always be used, if possible. Unknown is typically only used when
* automatically converting errors that do not contain an Id.
* @name UnknownError
@@ -21,7 +24,10 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
- * InternalError means an internal error has occurred. A more specific error
+ * @summary
+ * InternalError means an internal error has occurred.
+ * @description
+ * A more specific error
* should always be used, if possible.
* @name InternalError
* @constructor
@@ -32,6 +38,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* NotImplementedError means that the request type is valid but that the method
* to handle the request has not been implemented.
* @param {module:vanadium.context.Context} ctx The context the error was
@@ -43,6 +50,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* EndOfFileError means the end-of-file has been reached; more generally, no
* more input data is available.
* @param {module:vanadium.context.Context} ctx The context the error was
@@ -54,6 +62,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* BadArgError means the arguments to an operation are invalid or incorrectly
* formatted.
* @param {module:vanadium.context.Context} ctx The context the error was
@@ -65,6 +74,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* BadStateError means an operation was attempted on an object while the object
* was in an incompatible state.
* @param {module:vanadium.context.Context} ctx The context the error was
@@ -76,9 +86,13 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
- * BadVersion means the version presented by the client (e.g. to a service
- * that supports content-hash-based caching or atomic read-modify-write) was
- * out of date or otherwise invalid, likely because some other request caused
+ * @summary
+ * BadVersion means the version presented by the client was was
+ * out of date or otherwise invalid.
+ * @description
+ * The version presented by the client (e.g. to a service
+ * that supports content-hash-based caching or atomic read-modify-write) could
+ * be out of date or otherwise invalid, likely because some other request caused
* the version at the server to change. The client should get a fresh version
* and try again.
* @param {module:vanadium.context.Context} ctx The context the error was
@@ -90,7 +104,10 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
- * ExistError means that the requested item already exists; typically returned
+ * @summary
+ * ExistError means that the requested item already exists.
+ * @description
+ * Typically returned
* when an attempt to create an item fails because it already exists.
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
@@ -101,7 +118,10 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
- * NoExistError means that the requested item does not exist; typically returned
+ * @summary
+ * NoExistError means that the requested item does not exist.
+ * @description
+ * Typically returned
* when an attempt to lookup an item fails because it does not exist.
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
@@ -112,8 +132,11 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* NoExistOrNoAccessError means that either the requested item does not exist,
- * or is inaccessible. Typically returned when the distinction between
+ * or is inaccessible.
+ * @description
+ * Typically returned when the distinction between
* existence and inaccessiblity should be hidden to preserve privacy.
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
@@ -124,6 +147,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* NoServersError means a name was resolved to unusable or inaccessible servers.
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
@@ -134,6 +158,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* NoAccessError means the server does not authorize the client for access.
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
@@ -144,6 +169,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* NotTrustedError means the client does not trust the server.
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
@@ -154,8 +180,11 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* AbortedError means that an operation was not completed because it was aborted
- * by the receiver. A more specific error should be used if it would help the
+ * by the receiver.
+ * @description
+ * A more specific error should be used if it would help the
* caller decide how to proceed.
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
@@ -166,6 +195,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* BadProtocolError means that an operation was not completed because of a
* protocol or codec error.
* @param {module:vanadium.context.Context} ctx The context the error was
@@ -177,6 +207,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* CanceledError means the operation was not completed because it was explicitly
* cancelled by the caller.
* @param {module:vanadium.context.Context} ctx The context the error was
@@ -188,6 +219,7 @@
* @augments module:vanadium.verror.VanadiumError
*/
/**
+ * @summary
* TimeoutError means that an operation was not completed before the time
* deadline for the operation.
* @param {module:vanadium.context.Context} ctx The context the error was
diff --git a/src/verror/index.js b/src/verror/index.js
index 0cabef4..31c4831 100644
--- a/src/verror/index.js
+++ b/src/verror/index.js
@@ -28,7 +28,7 @@
* error messages to be generated in different languages.</p>
*
* @namespace
- * @name errors
+ * @name verror
* @memberof module:vanadium
*/
module.exports = extend(require('../gen-vdl/v.io/v23/verror'), {
diff --git a/src/verror/make-errors.js b/src/verror/make-errors.js
index a91e5e7..cbae09a 100644
--- a/src/verror/make-errors.js
+++ b/src/verror/make-errors.js
@@ -14,19 +14,22 @@
* and retryCode passed in.
* @param {string} id The unique id for this error type. It is preferable
* to prefix the error name with a package path that is unique.
- * @param {string} retryCode The retry action for this error.
+ * @param {module:vanadium.verror.actions} retryCode The retry action for this
+ * error.
* @param {string|object} format If a string, then it's the en-US text string,
* 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 {constructor} A constructor that can be used to create vanadium
- * errors with the given error id.
+ * @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) {
var fname = id.split('.').pop();
var Errors = {};
- Errors[fname] = function () {
+ Errors[fname] = function() {
var args = Array.prototype.slice.call(arguments);
if (Array.isArray(args[0]) && args.length === 1) {
args = args[0];
@@ -42,7 +45,9 @@
Errors[fname].prototype._argTypes = types || [];
errorMap[id] = Errors[fname];
if (typeof format === 'string') {
- format = { 'en-US': format };
+ format = {
+ 'en-US': format
+ };
}
if (format) {
@@ -53,6 +58,4 @@
}
}
return Errors[fname];
-}
-
-
+}
\ No newline at end of file
diff --git a/src/verror/vanadium-error.js b/src/verror/vanadium-error.js
index e84ecde..c58026b 100644
--- a/src/verror/vanadium-error.js
+++ b/src/verror/vanadium-error.js
@@ -11,16 +11,26 @@
module.exports = VanadiumError;
/**
+ * @summary
* The base error for all vanadium wire errors. This class should not
* be used directly, but all vanadium errors should inherit from
* VanadiumError.
* @constructor
* @memberof module:vanadium.verror
- * @param {string} id The errorId for the error
- * @param {string} retryCode The retry behavior for this error
+ * @param {string} id The unique id for this error type. It is preferable
+ * to prefix the error name with a package path that is unique.
+ * @param {module:vanadium.verror.actions} retryCode The retry action for
+ * this error.
* @param {module:vanadium.context.Context} ctx The context the error was
* created in.
- * @param {...*} params A list of parameters to include in the error message
+ * @param {...*} params A list of parameters to include in the error message.
+ *
+ * @property {string} id The unique id for this error type.
+ * @property {module:vanadium.verror.actions} retryCode The retry action for
+ * this error.
+ * @property {Array.<*>} paramList A list of parameters to included in the error
+ * message
+ * this error.
*/
function VanadiumError() {
var args = Array.prototype.slice.call(arguments);
@@ -79,8 +89,8 @@
VanadiumError.prototype._type = Types.ERROR.elem;
/**
- * Clones the error
- * @return {VanadiumError} A deep copy of the error
+ * Clones the error.
+ * @return {module:vanadium.verror.VanadiumError} A deep copy of the error.
*/
VanadiumError.prototype.clone = function() {
var res = Object.create(this.constructor.prototype);
