Use @typeparam` in docstrings for front end and connectors.

packages/application/src/frontend.ts

@@ -18,23 +18,18 @@ import { Widget } from '@phosphor/widgets';
 /**
  * The type for all JupyterFrontEnd application plugins.
  *
- * #### Notes
- * The generic `T` argument indicates the type that the plugin `provides` upon
- * being activated.
+ * @typeparam T - The type that the plugin `provides` upon being activated.
  */
 export type JupyterFrontEndPlugin<T> = IPlugin<JupyterFrontEnd, T>;
 
 /**
  * The base Jupyter front-end application class.
  *
+ * @typeparam `T` - The `shell` type. Defaults to `JupyterFrontEnd.IShell`.
+ *
  * #### Notes
  * This type is useful as a generic application against which front-end plugins
  * can be authored. It inherits from the phosphor `Application`.
- *
- * The generic type argument semantics are as follows.
- *
- * `T extends JupyterFrontEnd.Shell = JupyterFrontEnd.Shell` - the type of the
- * `shell` attribute of a `JupyterFrontEnd`.
  */
 export abstract class JupyterFrontEnd<
   T extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell

packages/coreutils/src/dataconnector.ts

@@ -6,23 +6,21 @@ import { IDataConnector } from './interfaces';
 /**
  * An abstract class that adheres to the data connector interface.
  *
+ * @typeparam T - The basic entity response type a service's connector.
+ *
+ * @typeparam U - The basic entity request type, which is conventionally the
+ * same as the response type but may be different if a service's implementation
+ * requires input data to be different from output responses. Defaults to `T`.
+ *
+ * @typeparam V - The basic token applied to a request, conventionally a string
+ * ID or filter, but may be set to a different type when an implementation
+ * requires it. Defaults to `string`.
+ *
  * #### Notes
  * The only abstract method in this class is the `fetch` method, which must be
  * reimplemented by all subclasses. The `remove` and `save` methods have a
  * default implementation that returns a promise that will always reject. This
  * class is a convenience superclass for connectors that only need to `fetch`.
- *
- * The generic type arguments <T, U = T, V = string> semantics are:
- *
- * T - is the basic entity response type a particular service's connector.
- *
- * U = T - is the basic entity request type, which is conventionally the same as
- * the response type but may be different if a service's implementation requires
- * input data to be different from output responses.
- *
- * V = string - is the basic token applied to a request, conventionally a string
- * ID or filter, but may be set to a different type when an implementation
- * requires it.
  */
 export abstract class DataConnector<T, U = T, V = string>
   implements IDataConnector<T, U, V> {
@@ -37,7 +35,7 @@ export abstract class DataConnector<T, U = T, V = string>
    * The promise returned by this method may be rejected if an error occurs in
    * retrieving the data. Nonexistence of an `id` will succeed with `undefined`.
    */
-  abstract fetch(id: V): Promise<T | undefined>;
+  abstract async fetch(id: V): Promise<T | undefined>;
 
   /**
    * Retrieve the list of items available from the data connector.
@@ -49,8 +47,8 @@ export abstract class DataConnector<T, U = T, V = string>
    * #### Notes
    * Subclasses should reimplement if they support a back-end that can list.
    */
-  list(query?: any): Promise<{ ids: V[]; values: T[] }> {
-    return Promise.reject(new Error('list method has not been implemented.'));
+  async list(query?: any): Promise<{ ids: V[]; values: T[] }> {
+    throw new Error('DataConnector#list method has not been implemented.');
   }
 
   /**
@@ -63,8 +61,8 @@ export abstract class DataConnector<T, U = T, V = string>
    * #### Notes
    * Subclasses should reimplement if they support a back-end that can remove.
    */
-  remove(id: V): Promise<any> {
-    return Promise.reject(new Error('remove method has not been implemented.'));
+  async remove(id: V): Promise<any> {
+    throw new Error('DataConnector#remove method has not been implemented.');
   }
 
   /**
@@ -79,7 +77,7 @@ export abstract class DataConnector<T, U = T, V = string>
    * #### Notes
    * Subclasses should reimplement if they support a back-end that can save.
    */
-  save(id: V, value: U): Promise<any> {
-    return Promise.reject(new Error('save method has not been implemented.'));
+  async save(id: V, value: U): Promise<any> {
+    throw new Error('DataConnector#save method has not been implemented.');
   }
 }

packages/coreutils/src/interfaces.ts

@@ -24,18 +24,15 @@ export interface IChangedArgs<T> {
 /**
  * The description of a general purpose data connector.
  *
- * #### Notes
- * The generic type arguments <T, U = T, V = string> semantics are:
+ * @typeparam T - The basic entity response type a service's connector.
  *
- * T - is the basic entity response type a particular service's connector.
+ * @typeparam U - The basic entity request type, which is conventionally the
+ * same as the response type but may be different if a service's implementation
+ * requires input data to be different from output responses. Defaults to `T`.
  *
- * U = T - is the basic entity request type, which is conventionally the same as
- * the response type but may be different if a service's implementation requires
- * input data to be different from output responses.
- *
- * V = string - is the basic token applied to a request, conventionally a string
+ * @typeparam V - The basic token applied to a request, conventionally a string
  * ID or filter, but may be set to a different type when an implementation
- * requires it.
+ * requires it. Defaults to `string`.
  */
 export interface IDataConnector<T, U = T, V = string> {
   /**