xtralab 0.15.0 → 0.15.1

package/src/git/commands.ts

@@ -28,16 +28,25 @@ export namespace CommandIDs {
  * Argument shapes used by {@link CommandIDs.openDiff}.
  */
 export namespace CommandArguments {
+  /**
+   * The arguments for the open-diff command.
+   */
   export interface IOpenDiff {
+    /**
+     * The server-relative path of the repository containing the change.
+     */
     repoPath: string;
+    /**
+     * The file change to show.
+     */
     change: IFileChange;
+    /**
+     * Whether to open the diff as a pinned tab instead of the shared preview.
+     */
     pin?: boolean;
   }
 }
 
-/**
- * Widget id of the single, reused preview diff tab.
- */
 export const PREVIEW_DIFF_WIDGET_ID = 'xtralab:diff:preview';
 
 /**
@@ -70,14 +79,23 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
     this._trans = trans;
   }
 
+  /**
+   * The file change currently displayed.
+   */
   get change(): IFileChange {
     return this._change;
   }
 
+  /**
+   * Whether the widget is pinned rather than the shared preview.
+   */
   get pinned(): boolean {
     return this._pinned;
   }
 
+  /**
+   * Pin the widget; a no-op when already pinned.
+   */
   pin(): void {
     if (this._pinned) {
       return;
@@ -86,10 +104,16 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
     this._pinnedChanged.emit(true);
   }
 
+  /**
+   * A signal emitted when the widget becomes pinned.
+   */
   get pinnedChanged(): ISignal<this, boolean> {
     return this._pinnedChanged;
   }
 
+  /**
+   * Display a new file change and update the tab title, caption, and icon.
+   */
   setChange(repoPath: string, change: IFileChange): void {
     this._change = change;
     this.content.setModel(fileChangeToDiffModel(repoPath, change));
@@ -104,21 +128,48 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
   private _pinnedChanged = new Signal<this, boolean>(this);
 }
 
+/**
+ * The options used to create a diff main area widget.
+ */
 interface ICreateDiffWidgetOptions {
+  /**
+   * The server-relative path of the repository containing the change.
+   */
   repoPath: string;
+  /**
+   * The file change to display.
+   */
   change: IFileChange;
+  /**
+   * Theme manager the diff view follows; may be `null`.
+   */
   themeManager: IThemeManager | null;
+  /**
+   * Contents manager used to write hunk-discard results.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * Rendermime registry used by notebook diffs; may be `null`.
+   */
   rendermime: IRenderMimeRegistry | null;
+  /**
+   * Ask-agent popup for prompting an agent about diff lines; may be `null`.
+   */
   askAgent: IAskAgent | null;
+  /**
+   * Translation bundle for user-facing strings.
+   */
   trans: TranslationBundle;
+  /**
+   * Whether the widget opens pinned instead of as the shared preview.
+   */
   pinned?: boolean;
+  /**
+   * Callback invoked when the widget becomes pinned.
+   */
   onPinned?: (widget: DiffMainAreaWidget) => void;
 }
 
-/**
- * Build the launcher's diff tab around the shared diff widget.
- */
 function createDiffWidget(
   options: ICreateDiffWidgetOptions
 ): DiffMainAreaWidget {
@@ -158,7 +209,6 @@ function createDiffWidget(
   widget.toolbar.addItem('pin', pinButton);
   addDiffToolbarItems(widget.toolbar, content);
 
-  // Keep chrome visible only while there is a relevant toolbar control.
   const syncToolbarVisibility = (): void => {
     if (widget.isDisposed) {
       return;
@@ -186,7 +236,6 @@ function createDiffWidget(
     }
     syncToolbarVisibility();
   };
-  // Auto-close once a discard leaves nothing to show.
   const onEmptied = (): void => {
     if (!widget.isDisposed) {
       widget.close();
@@ -206,8 +255,17 @@ function createDiffWidget(
   return widget;
 }
 
+/**
+ * The options for {@link registerGitCommands}.
+ */
 interface IRegisterGitCommandsOptions {
+  /**
+   * The JupyterLab application, providing the commands registry and shell.
+   */
   app: JupyterFrontEnd;
+  /**
+   * Theme manager the diff views follow; may be `null`.
+   */
   themeManager: IThemeManager | null;
   /**
    * Contents manager used to write hunk-discard results.
@@ -233,12 +291,14 @@ interface IRegisterGitCommandsOptions {
    * Look up an already-open diff widget for a file change.
    */
   findDiff(change: IFileChange, pin?: boolean): DiffMainAreaWidget | undefined;
+  /**
+   * Callback invoked when a preview diff widget becomes pinned.
+   */
   onPinned(widget: DiffMainAreaWidget): void;
 }
 
 /**
- * Register the launcher's git diff command on the application command
- * registry.
+ * Register the launcher's git diff command.
  */
 export function registerGitCommands(
   options: IRegisterGitCommandsOptions

package/src/git/diffModel.ts

@@ -80,14 +80,39 @@ class FileChangeDiffModel implements IXtralabDiffModel {
     };
   }
 
+  /**
+   * A signal emitted when the reference or challenger changes; this static
+   * model never emits it.
+   */
   readonly changed: ISignal<Git.Diff.IModel, Git.Diff.IModelChange> =
     new Signal<Git.Diff.IModel, Git.Diff.IModelChange>(this);
+  /**
+   * The reference (old) side of the diff.
+   */
   reference: Git.Diff.IContent;
+  /**
+   * The challenger (new) side of the diff.
+   */
   challenger: Git.Diff.IContent;
+  /**
+   * Repo-relative path of the changed file.
+   */
   readonly filename: string;
+  /**
+   * The rename source path; `undefined` for non-renames.
+   */
   readonly oldFilename: string | undefined;
+  /**
+   * Path of the git repository, relative to the server root.
+   */
   readonly repositoryPath: string;
+  /**
+   * Whether the file content is binary.
+   */
   readonly isBinary: boolean;
+  /**
+   * Whether hunks can be discarded through a working-tree save.
+   */
   readonly canDiscard: boolean;
 }