Documentation updates and code reorganization.

packages/services/src/kernel/default.ts

@@ -586,43 +586,23 @@ class DefaultKernel implements Kernel.IKernel {
   }
 
   /**
-   * Register an IOPub message hook.
-   *
-   * @param msg_id - The parent_header message id the hook will intercept.
-   *
-   * @param hook - The callback invoked for the message.
-   *
-   * @returns A disposable used to unregister the message hook.
+   * Connect to a comm, or create a new one.
    *
    * #### Notes
-   * The IOPub hook system allows you to preempt the handlers for IOPub messages
-   * with a given parent_header message id. The most recently registered hook is
-   * run first. If the hook returns false, any later hooks and the future's
-   * onIOPub handler will not run. If a hook throws an error, the error is
-   * logged to the console and the next hook is run. If a hook is registered
-   * during the hook processing, it won't run until the next message. If a hook
-   * is disposed during the hook processing, it will be deactivated immediately.
-   *
-   * See also [[IFuture.registerMessageHook]].
-   *
-   * TODO: like phosphor, perhaps we shouldn't return a disposable, which keeps
-   * a basically just keeps a reference to the msgId. Instead, just make the
-   * user call a new removeMessageHook function directly (presumably it's just
-   * as easy to keep the message id and hook function as it is to keep the
-   * disposable, so might as well avoid the allocation).
+   * If a client-side comm already exists with the given commId, it is returned.
    */
-  registerMessageHook(msgId: string, hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): IDisposable {
-    let future = this._futures && this._futures.get(msgId);
-    if (future) {
-      future.registerMessageHook(hook);
+  connectToComm(targetName: string, commId: string = uuid()): Kernel.IComm {
+    if (this._comms.has(commId)) {
+      return this._comms.get(commId);
     }
-
-    return new DisposableDelegate(() => {
-      let future = this._futures && this._futures.get(msgId);
-      if (future) {
-        future.removeMessageHook(hook);
-      }
-    });
+    let comm = new CommHandler(
+      targetName,
+      commId,
+      this,
+      () => { this._unregisterComm(commId); }
+    );
+    this._comms.set(commId, comm);
+    return comm;
   }
 
   /**
@@ -643,7 +623,7 @@ class DefaultKernel implements Kernel.IKernel {
    * If the callback returns a promise, kernel message processing will pause
    * until the returned promise is fulfilled.
    *
-   * TODO: perhaps, just like with registerMessageHook above, we should just
+   * TODO: perhaps, just like with registerMessageHook, we should just
    * provide a removeCommTarget function instead of returning a disposable.
    * Presumably it's just as easy for someone to store the comm target name as
    * it is to store the disposable. Since there is only one callback, you don't even
@@ -659,25 +639,52 @@ class DefaultKernel implements Kernel.IKernel {
   }
 
   /**
-   * Connect to a comm, or create a new one.
+   * Register an IOPub message hook.
+   *
+   * @param msg_id - The parent_header message id the hook will intercept.
+   *
+   * @param hook - The callback invoked for the message.
+   *
+   * @returns A disposable used to unregister the message hook.
    *
    * #### Notes
-   * If a client-side comm already exists with the given commId, it is returned.
+   * The IOPub hook system allows you to preempt the handlers for IOPub
+   * messages that are responses to a given message id.
+   *
+   * The most recently registered hook is run first. A hook can return a
+   * boolean or a promise to a boolean, in which case all kernel message
+   * processing pauses until the promise is fulfilled. If a hook return value
+   * resolves to false, any later hooks will not run and the function will
+   * return a promise resolving to false. If a hook throws an error, the error
+   * is logged to the console and the next hook is run. If a hook is
+   * registered during the hook processing, it will not run until the next
+   * message. If a hook is removed during the hook processing, it will be
+   * deactivated immediately.
+   *
+   * See also [[IFuture.registerMessageHook]].
+   *
+   * TODO: like phosphor, perhaps we shouldn't return a disposable, which keeps
+   * a basically just keeps a reference to the msgId. Instead, just make the
+   * user call a new removeMessageHook function directly (presumably it's just
+   * as easy to keep the message id and hook function as it is to keep the
+   * disposable, so might as well avoid the allocation).
    */
-  connectToComm(targetName: string, commId: string = uuid()): Kernel.IComm {
-    if (this._comms.has(commId)) {
-      return this._comms.get(commId);
+  registerMessageHook(msgId: string, hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): IDisposable {
+    let future = this._futures && this._futures.get(msgId);
+    if (future) {
+      future.registerMessageHook(hook);
     }
-    let comm = new CommHandler(
-      targetName,
-      commId,
-      this,
-      () => { this._unregisterComm(commId); }
-    );
-    this._comms.set(commId, comm);
-    return comm;
+
+    return new DisposableDelegate(() => {
+      let future = this._futures && this._futures.get(msgId);
+      if (future) {
+        future.removeMessageHook(hook);
+      }
+    });
   }
 
+
+
   /**
    * Handle a message with a display id.
    *

packages/services/src/kernel/future.ts

@@ -19,6 +19,11 @@ import {
 
 /**
  * Implementation of a kernel future.
+ *
+ * If a reply is expected, the Future is considered done when both a `reply`
+ * message and an `idle` iopub status message have been received.  Otherwise, it
+ * is considered done when the `idle` status is received.
+ *
  */
 export
 class KernelFutureHandler extends DisposableDelegate implements Kernel.IFuture {
@@ -97,12 +102,18 @@ class KernelFutureHandler extends DisposableDelegate implements Kernel.IFuture {
    * @param hook - The callback invoked for an IOPub message.
    *
    * #### Notes
-   * The IOPub hook system allows you to preempt the handlers for IOPub messages handled
-   * by the future. The most recently registered hook is run first.
-   * If the hook returns false, any later hooks and the future's onIOPub handler will not run.
-   * If a hook throws an error, the error is logged to the console and the next hook is run.
-   * If a hook is registered during the hook processing, it won't run until the next message.
-   * If a hook is removed during the hook processing, it will be deactivated immediately.
+   * The IOPub hook system allows you to preempt the handlers for IOPub
+   * messages handled by the future.
+   *
+   * The most recently registered hook is run first. A hook can return a
+   * boolean or a promise to a boolean, in which case all kernel message
+   * processing pauses until the promise is fulfilled. If a hook return value
+   * resolves to false, any later hooks will not run and the function will
+   * return a promise resolving to false. If a hook throws an error, the error
+   * is logged to the console and the next hook is run. If a hook is
+   * registered during the hook processing, it will not run until the next
+   * message. If a hook is removed during the hook processing, it will be
+   * deactivated immediately.
    */
   registerMessageHook(hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): void {
     if (this.isDisposed) {
@@ -269,16 +280,17 @@ namespace Private {
     /**
      * Process a message through the hooks.
      *
-     * @returns a promise resolving to false if any hook resolved as false, otherwise true
+     * @returns a promise resolving to false if any hook resolved as false,
+     * otherwise true
      *
      * #### Notes
-     * The hooks can be asynchronous, returning a promise, and hook processing
-     * pauses until the promise resolves. The most recently registered hook is
-     * run first. If a hook returns false (or a promise resolving to false), any
+     * The most recently registered hook is run first. A hook can return a
+     * boolean or a promise to a boolean, in which case processing pauses until
+     * the promise is fulfilled. If a hook return value resolves to false, any
      * later hooks will not run and the function will return a promise resolving
      * to false. If a hook throws an error, the error is logged to the console
      * and the next hook is run. If a hook is registered during the hook
-     * processing, it won't run until the next message. If a hook is removed
+     * processing, it will not run until the next message. If a hook is removed
      * during the hook processing, it will be deactivated immediately.
      */
     async process(msg: T): Promise<boolean> {

packages/services/src/kernel/kernel.ts

@@ -138,9 +138,8 @@ namespace Kernel {
      * @returns A promise that resolves when the kernel has reconnected.
      *
      * #### Notes
-     * This is not actually a standard HTTP request, but useful function
-     * nonetheless for reconnecting to the kernel if the connection is somehow
-     * lost.
+     * This just refreshes the connection to an existing kernel, and does not
+     * perform an HTTP request to the server or restart the kernel.
      */
     reconnect(): Promise<void>;
 
@@ -318,28 +317,35 @@ namespace Kernel {
      * @returns A disposable used to unregister the comm target.
      *
      * #### Notes
-     * Only one comm target can be registered at a time, an existing
-     * callback will be overidden.  A registered comm target handler will take
-     * precedence over a comm which specifies a `target_module`.
+     * Only one comm target can be registered to a target name at a time, an
+     * existing callback for the same target name will be overidden.  A registered
+     * comm target handler will take precedence over a comm which specifies a
+     * `target_module`.
+     *
+     * If the callback returns a promise, kernel message processing will pause
+     * until the returned promise is fulfilled.
      */
     registerCommTarget(targetName: string, callback: (comm: Kernel.IComm, msg: KernelMessage.ICommOpenMsg) => void | PromiseLike<void>): IDisposable;
 
     /**
      * Register an IOPub message hook.
      *
-     * @param msg_id - The parent_header message id in messages the hook should intercept.
+     * @param msg_id - The parent_header message id in messages the hook should
+     * intercept.
      *
      * @param hook - The callback invoked for the message.
      *
      * @returns A disposable used to unregister the message hook.
      *
      * #### Notes
-     * The IOPub hook system allows you to preempt the handlers for IOPub messages with a
-     * given parent_header message id. The most recently registered hook is run first.
-     * If the hook returns false, any later hooks and the future's onIOPub handler will not run.
-     * If a hook throws an error, the error is logged to the console and the next hook is run.
-     * If a hook is registered during the hook processing, it won't run until the next message.
-     * If a hook is disposed during the hook processing, it will be deactivated immediately.
+     * The IOPub hook system allows you to preempt the handlers for IOPub
+     * messages with a given parent_header message id. The most recently
+     * registered hook is run first. If a hook return value resolves to false,
+     * any later hooks and the future's onIOPub handler will not run. If a hook
+     * throws an error, the error is logged to the console and the next hook is
+     * run. If a hook is registered during the hook processing, it will not run
+     * until the next message. If a hook is disposed during the hook processing,
+     * it will be deactivated immediately.
      *
      * See also [[IFuture.registerMessageHook]].
      */
@@ -362,20 +368,22 @@ namespace Kernel {
     statusChanged: ISignal<this, Kernel.Status>;
 
     /**
-     * A signal emitted for iopub kernel messages.
+     * A signal emitted after an iopub kernel message is handled.
      */
     iopubMessage: ISignal<this, KernelMessage.IIOPubMessage>;
 
     /**
-     * A signal emitted for unhandled kernel message.
+     * A signal emitted for unhandled non-iopub kernel messages that claimed to
+     * be responses for messages we sent.
      */
     unhandledMessage: ISignal<this, KernelMessage.IMessage>;
 
     /**
-     * A signal emitted for any kernel message.
+     * A signal emitted when any kernel message is sent or received.
      *
-     * The behavior is undefined if the message is modified during message
-     * handling. As such, the message should be treated as read-only.
+     * #### Notes
+     * This signal is emitted before any message handling has happened. The
+     * message should be treated as read-only.
      */
     anyMessage: ISignal<this, IAnyMessageArgs>;
 
@@ -392,14 +400,11 @@ namespace Kernel {
      * #### Notes
      * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels).
      *
-     * On a valid response, closes the websocket and disposes of the kernel
-     * object, and fulfills the promise.
-     *
-     * The promise will be rejected if the kernel status is `'dead'` or if the
-     * request fails or the response is invalid.
+     * On a valid response, closes the websocket, disposes of the kernel
+     * object, emits the [[terminated]] signal, and fulfills the promise.
      *
-     * If the server call is successful, the [[terminated]] signal will be
-     * emitted.
+     * The promise will be rejected if the kernel status is `'dead'`, the
+     * request fails, or the response is invalid.
      */
     shutdown(): Promise<void>;
   }
@@ -667,15 +672,10 @@ namespace Kernel {
   }
 
   /**
-   * Object providing a Future interface for message callbacks.
+   * A Future interface for responses from the kernel.
    *
-   * The future will self-dispose after `isDone` is
-   * set and the registered `onDone` handler is called.
-   *
-   * If a `reply` is expected, the Future is considered done when
-   * both a `reply` message and an `idle` iopub status message have
-   * been received.  Otherwise, it is considered done when the `idle` status is
-   * received.
+   * When a message is sent to a kernel, a Future is created to handle any
+   * responses that may come from the kernel.
    */
   export
   interface IFuture extends IDisposable {
@@ -687,16 +687,22 @@ namespace Kernel {
     /**
      * A promise that resolves when the future is done.
      *
-     * The contents of the promise is the reply message.
+     * The future is done when there are no more responses expected from the
+     * kernel.
+     *
+     * The `done` promise resolves to the reply message if there is one,
+     * otherwise it resolves to `undefined`.
      */
-    readonly done: Promise<KernelMessage.IShellMessage>;
+    readonly done: Promise<KernelMessage.IShellMessage | undefined>;
 
     /**
      * The reply handler for the kernel future.
      *
      * #### Notes
-     * If the handler returns a promise, message processing pauses until the
-     * promise is resolved.
+     * If the handler returns a promise, all kernel message processing pauses
+     * until the promise is resolved. If there is a reply message, the future
+     * `done` promise also resolves to the reply message after this handler has
+     * been called.
      */
     onReply: (msg: KernelMessage.IShellMessage) => void | PromiseLike<void>;
 
@@ -704,8 +710,8 @@ namespace Kernel {
      * The stdin handler for the kernel future.
      *
      * #### Notes
-     * If the handler returns a promise, message processing pauses until the
-     * promise is resolved.
+     * If the handler returns a promise, all kernel message processing pauses
+     * until the promise is resolved.
      */
     onStdin: (msg: KernelMessage.IStdinMessage) => void | PromiseLike<void>;
 
@@ -713,8 +719,8 @@ namespace Kernel {
      * The iopub handler for the kernel future.
      *
      * #### Notes
-     * If the handler returns a promise, message processing pauses until the
-     * promise is resolved.
+     * If the handler returns a promise, all kernel message processing pauses
+     * until the promise is resolved.
      */
     onIOPub: (msg: KernelMessage.IIOPubMessage) => void | PromiseLike<void>;
 
@@ -724,12 +730,18 @@ namespace Kernel {
      * @param hook - The callback invoked for an IOPub message.
      *
      * #### Notes
-     * The IOPub hook system allows you to preempt the handlers for IOPub messages handled
-     * by the future. The most recently registered hook is run first.
-     * If the hook returns false, any later hooks and the future's onIOPub handler will not run.
-     * If a hook throws an error, the error is logged to the console and the next hook is run.
-     * If a hook is registered during the hook processing, it won't run until the next message.
-     * If a hook is removed during the hook processing, it will be deactivated immediately.
+     * The IOPub hook system allows you to preempt the handlers for IOPub
+     * messages handled by the future.
+     *
+     * The most recently registered hook is run first. A hook can return a
+     * boolean or a promise to a boolean, in which case all kernel message
+     * processing pauses until the promise is fulfilled. If a hook return value
+     * resolves to false, any later hooks will not run and the function will
+     * return a promise resolving to false. If a hook throws an error, the error
+     * is logged to the console and the next hook is run. If a hook is
+     * registered during the hook processing, it will not run until the next
+     * message. If a hook is removed during the hook processing, it will be
+     * deactivated immediately.
      */
     registerMessageHook(hook: (msg: KernelMessage.IIOPubMessage) => boolean): void;
 
@@ -768,13 +780,19 @@ namespace Kernel {
      * Callback for a comm close event.
      *
      * #### Notes
-     * This is called when the comm is closed from either the server or
-     * client.
+     * This is called when the comm is closed from either the server or client.
+     * If this is called in response to a kernel message and the handler returns
+     * a promise, all kernel message processing pauses until the promise is
+     * resolved.
      */
     onClose: (msg: KernelMessage.ICommCloseMsg) => void | PromiseLike<void>;
 
     /**
      * Callback for a comm message received event.
+     *
+     * #### Notes
+     * If the handler returns a promise, all kernel message processing pauses
+     * until the promise is resolved.
      */
     onMsg: (msg: KernelMessage.ICommMsgMsg) => void | PromiseLike<void>;