Add documentation

Author: fcollonval

packages/docprovider/src/notebookCellExecutor.ts

@@ -11,11 +11,19 @@ import { nullTranslator } from '@jupyterlab/translation';
 import { ICollaborativeDrive } from './tokens';
 import { Dialog, showDialog } from '@jupyterlab/apputils';
 
+/**
+ * Notebook cell executor posting a request to the server for execution.
+ */
 export class NotebookCellServerExecutor implements INotebookCellExecutor {
   private _contents: Contents.IManager;
   private _drive: ICollaborativeDrive;
   private _serverSettings: ServerConnection.ISettings;
 
+  /**
+   * Constructor
+   *
+   * @param options Constructor options; the contents manager, the collaborative drive and optionally the server settings.
+   */
   constructor(options: {
     contents: Contents.IManager;
     drive: ICollaborativeDrive;
@@ -27,6 +35,12 @@ export class NotebookCellServerExecutor implements INotebookCellExecutor {
       options.serverSettings ?? ServerConnection.makeSettings();
   }
 
+  /**
+   * Execute a given cell of the notebook.
+   *
+   * @param options Execution options
+   * @returns Execution success status
+   */
   async runCell({
     cell,
     notebook,

packages/docprovider/src/tokens.ts

@@ -23,7 +23,10 @@ export type SharedDocumentFactory = (
   options: Contents.ISharedFactoryOptions
 ) => YDocument<DocumentChange>;
 
-export interface IRoomNameOptions {
+/**
+ * Options needed to build the room name for a file metadata.
+ */
+export interface IFileMetadata {
   /**
    * Document format; 'text', 'base64',...
    */
@@ -43,7 +46,12 @@ export interface IRoomNameOptions {
  * server using the Jupyter REST API and a WebSocket connection.
  */
 export interface ICollaborativeDrive extends Contents.IDrive {
-  getRoomName(options: IRoomNameOptions): string | null;
+  /**
+   * Get a room name for a given file.
+   *
+   * @param metadata File metadata
+   */
+  getRoomName(metadata: IFileMetadata): string | null;
   /**
    * SharedModel factory for the YDrive.
    */

packages/docprovider/src/ydrive.ts

@@ -12,7 +12,7 @@ import {
   ICollaborativeDrive,
   ISharedModelFactory,
   SharedDocumentFactory,
-  type IRoomNameOptions
+  type IFileMetadata
 } from './tokens';
 
 const DISABLE_RTC =
@@ -94,8 +94,14 @@ export class YDrive extends Drive implements ICollaborativeDrive {
     return super.get(localPath, options);
   }
 
-  getRoomName(options: IRoomNameOptions): string | null {
-    const key = `${options.format}:${options.type}:${options.localPath}`;
+  /**
+   * Get a room name for a given file.
+   *
+   * @param metadata File metadata
+   */
+  getRoomName(metadata: IFileMetadata): string | null {
+    // FIXME we have issue with that key in case of file rename
+    const key = `${metadata.format}:${metadata.type}:${metadata.localPath}`;
     const provider = this._providers.get(key);
     return provider?.roomName ?? null;
   }

packages/docprovider/src/yprovider.ts

@@ -77,6 +77,9 @@ export class WebSocketProvider implements IDocumentProvider {
     return this._ready.promise;
   }
 
+  /**
+   * Room name
+   */
   get roomName(): string | null {
     return this._yWebsocketProvider?.roomname ?? null;
   }