xtralab 0.15.0 → 0.15.2

package/src/menus/index.ts

@@ -10,15 +10,9 @@ import type { Menu, MenuBar, Widget } from '@lumino/widgets';
 const PLUGIN_ID = 'xtralab:menus';
 
 /**
- * Hide the "Run" and "Kernel" top-level menus while no kernel-using widget
- * is open in the main area. The agent-first launcher does not use kernels,
- * so showing those menus on a fresh workspace surfaces commands the user
- * cannot meaningfully invoke; remove them until a notebook or console is
- * opened, then restore them at their original ranks.
- *
- * Detection is duck-typed on `sessionContext`: NotebookPanel and ConsolePanel
- * both expose it, which avoids pulling in `@jupyterlab/notebook` and
- * `@jupyterlab/console` just to identify their widgets.
+ * Hide the Run and Kernel menus while no kernel-using widget is open in the
+ * main area, then restore them at their original ranks — the agent-first
+ * launcher does not use kernels, so a fresh workspace should not surface them.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -31,17 +25,14 @@ const plugin: JupyterFrontEndPlugin<void> = {
     mainMenu: IMainMenu,
     labShell: ILabShell
   ): void => {
-    // The interface types (IRunMenu, IKernelMenu) extend IRankedMenu, but
-    // the concrete instances are RankedMenu/Menu — cast so we can hand them
-    // to MenuBar.removeMenu and IMainMenu.addMenu, which expect a `Menu`.
+    // The interface types extend IRankedMenu but the concrete instances are
+    // RankedMenu/Menu; cast for the MenuBar methods, which expect a `Menu`.
     const menuBar = mainMenu as unknown as MenuBar;
     const runMenu = mainMenu.runMenu as unknown as Menu;
     const kernelMenu = mainMenu.kernelMenu as unknown as Menu;
 
-    // Capture the schema-assigned ranks so the menus reappear in their
-    // original slots between View (rank 3) and Tabs (rank 500). Falling
-    // back to the hard-coded defaults from `MainMenu` keeps things sane
-    // if the schema ever omits the rank.
+    // Schema-assigned ranks so the menus reappear in their original slots;
+    // fall back to MainMenu's hard-coded defaults if the schema omits them.
     const runRank = mainMenu.runMenu.rank ?? 4;
     const kernelRank = mainMenu.kernelMenu.rank ?? 5;
 
@@ -51,11 +42,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const update = (): void => {
       const show = hasKernelWidget(labShell);
       if (show) {
-        // Don't go through `mainMenu.addMenu`: it picks the insertion index
-        // from a private `_items` array that `removeMenu` doesn't update,
-        // so re-adding lands the menu at the wrong position. Insert
-        // directly on the MenuBar by walking current menus and finding
-        // the first sibling with a higher rank.
+        // Not `mainMenu.addMenu`: its insertion index comes from a private
+        // `_items` array that `removeMenu` doesn't update, misplacing re-adds.
         if (!isPresent(runMenu)) {
           insertByRank(menuBar, runMenu, runRank);
         }
@@ -80,11 +68,9 @@ const plugin: JupyterFrontEndPlugin<void> = {
 };
 
 /**
- * True iff any widget in the main area exposes a `sessionContext` — the
- * shared marker for NotebookPanel, ConsolePanel, and kernel-attached file
- * editors. We don't import their concrete types because that would drag
- * `@jupyterlab/notebook` and `@jupyterlab/console` into xtralab's bundle
- * just to do an `instanceof` check.
+ * True iff any main-area widget exposes a `sessionContext` (NotebookPanel,
+ * ConsolePanel, kernel-attached editors) — duck-typed to keep
+ * `@jupyterlab/notebook` and `@jupyterlab/console` out of the bundle.
  */
 function hasKernelWidget(labShell: ILabShell): boolean {
   for (const widget of labShell.widgets('main')) {
@@ -103,10 +89,8 @@ function hasSessionContext(widget: Widget): boolean {
 }
 
 /**
- * Insert `menu` into `menuBar` at the position dictated by `rank`, using
- * the existing menus' ranks to find the slot. Menus without a numeric
- * rank are treated as +Infinity so they sink to the end (matching the
- * convention in `MenuFactory.createMenus`).
+ * Insert `menu` at the slot dictated by `rank`; rank-less menus count as
+ * +Infinity and sink to the end, matching `MenuFactory.createMenus`.
  */
 function insertByRank(menuBar: MenuBar, menu: Menu, rank: number): void {
   const menus = menuBar.menus;

package/src/omnibox/files.ts

@@ -2,23 +2,21 @@ import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';
 
 /**
- * Shape of the `jupyterlab-quickopen` `api/files` response: a map from each
- * directory (relative to the server root, `""` for the root itself) to the
- * bare filenames it contains.
+ * Shape of the `jupyterlab-quickopen` `api/files` response: directory
+ * (relative to the server root, `""` for the root) to bare filenames.
  */
 interface IQuickOpenContents {
+  /**
+   * Filenames grouped by their containing directory.
+   */
   contents: { [dir: string]: string[] };
 }
 
 /**
  * Fetch and flatten the workspace file list from `jupyterlab-quickopen`'s
- * server endpoint (`GET {base}/jupyterlab-quickopen/api/files`).
- *
- * We reuse quickopen's endpoint rather than walking the contents API so the
- * listing honors the same server-side `.gitignore` filtering quickopen does
- * (xtralab ships `respectGitignore: true`) in a single request. The endpoint
- * only exists when quickopen's server extension is installed and the server
- * reads a local filesystem; callers treat a rejection as "no file results".
+ * server endpoint, which applies server-side `.gitignore` filtering in one
+ * request. Rejects when the server extension is absent; callers treat that as
+ * "no file results".
  */
 async function fetchWorkspaceFiles(respectGitignore = true): Promise<string[]> {
   const settings = ServerConnection.makeSettings();
@@ -54,10 +52,8 @@ const CACHE_TTL_MS = 15_000;
 let cache: { at: number; files: Promise<string[]> } | null = null;
 
 /**
- * The workspace file list, cached briefly so reopening the omnibox in quick
- * succession reuses one scan. A failed fetch (e.g. quickopen's server
- * extension is absent) resolves to an empty list so file search degrades to
- * "no results" instead of surfacing an error.
+ * The workspace file list, cached briefly so reopening the omnibox reuses one
+ * scan. A failed fetch resolves to an empty list.
  */
 export function loadWorkspaceFiles(): Promise<string[]> {
   const now = Date.now();

package/src/omnibox/index.ts

@@ -17,20 +17,10 @@ import { OmniboxWidget } from './widget';
 const PLUGIN_ID = 'xtralab:omnibox';
 
 /**
- * The omnibox: a single launcher overlay that fuzzy-searches workspace files
- * (via jupyterlab-quickopen's gitignore-aware endpoint) and JupyterLab
- * commands (the command palette's entries plus registry commands the palette
- * doesn't list), and routes a typed prompt to one of the configured agents
- * (running it in a fresh terminal through the launcher's
- * `xtralab:start-agent:<id>` commands). It is opened by the top-bar command
- * bar.
- *
- * Commands run and files opened through the overlay are remembered (persisted
- * in the state database) and offered again at the top while the query is
- * empty; the `maxNumberRecents` setting caps how many of each are kept.
- *
- * The agent rows come from the launcher's `IAgentRegistry`; when the launcher
- * is disabled the omnibox still searches files and commands.
+ * The omnibox: a launcher overlay that fuzzy-searches workspace files and
+ * commands and routes a typed prompt to a configured agent in a fresh
+ * terminal. Recently used commands and files persist in the state database;
+ * without the launcher it still searches files and commands.
  */
 const plugin: JupyterFrontEndPlugin<IOmnibox> = {
   id: PLUGIN_ID,
@@ -57,12 +47,8 @@ const plugin: JupyterFrontEndPlugin<IOmnibox> = {
     const trans = (translator ?? nullTranslator).load('jupyterlab');
     const placeholder = trans.__('Search files and commands, or ask an agent…');
 
-    // The palette's items carry per-item args (e.g. one "Use Theme: …" per
-    // theme) that a raw command-registry scan can't see, but `ICommandPalette`
-    // exposes no item list and the widget itself is unreachable through the
-    // shell (`LabShell.add` defers it until layout restore, after which the
-    // modal setting re-parents it out of the left area). The wrapper's
-    // `_palette` field is private in TypeScript only, so read it guarded.
+    // `ICommandPalette` exposes no item list and the palette widget is
+    // unreachable through the shell; duck-read the wrapper's TS-only-private `_palette`.
     const paletteItems = (): ReadonlyArray<CommandPalette.IItem> => {
       const widget = (palette as unknown as { _palette?: unknown } | null)
         ?._palette;
@@ -71,10 +57,8 @@ const plugin: JupyterFrontEndPlugin<IOmnibox> = {
 
     const recents = new OmniboxRecents({ state });
 
-    // Restore the persisted recents only after the configured cap is known:
-    // `restore` trims to `maxItems`, so restoring at the constructor default
-    // would permanently drop entries beyond it whenever the user configured a
-    // larger cap and the state fetch won the race against the settings load.
+    // Restore only after the configured cap is known: `restore` trims to
+    // `maxItems`, so restoring at the default could permanently drop entries.
     if (settingRegistry) {
       void settingRegistry
         .load(PLUGIN_ID)
@@ -110,7 +94,7 @@ const plugin: JupyterFrontEndPlugin<IOmnibox> = {
 
     const open = (query?: string): void => {
       // Reopen fresh each time so the input resets and the agent snapshot is
-      // current; the file list is cached separately (see files.ts).
+      // current; the file list stays cached (files.ts).
       close();
       const widget = new OmniboxWidget({
         commands,
@@ -136,7 +120,6 @@ const plugin: JupyterFrontEndPlugin<IOmnibox> = {
       label: trans.__('Search…'),
       caption: trans.__('Search files and commands, or ask an agent'),
       execute: args => {
-        // Toggle: a second press (e.g. of the keyboard shortcut) closes it.
         if (current && !current.isDisposed) {
           close();
           return;
@@ -146,7 +129,6 @@ const plugin: JupyterFrontEndPlugin<IOmnibox> = {
       }
     });
 
-    // Open the omnibox with Cmd/Ctrl+K, the common "command center" chord.
     commands.addKeyBinding({
       command: OMNIBOX_OPEN_COMMAND,
       keys: ['Accel K'],

package/src/omnibox/model.ts

@@ -11,15 +11,15 @@ import { agentCommandId } from '../launcher/tokens';
 
 import type { OmniboxRecents, RecentKind } from './recents';
 
-/**
- * The source a result row came from, used to group rows under a header.
- */
 type OmniboxItemKind = 'command' | 'file' | 'agent';
 
 /**
  * A single result row, with the action it runs when chosen.
  */
 export interface IOmniboxItem {
+  /**
+   * The source category of the row: command, file, or agent.
+   */
   kind: OmniboxItemKind;
   /**
    * Stable React key.
@@ -55,49 +55,73 @@ interface IOmniboxSections {
    * Recently used commands and files, shown while the term is empty.
    */
   recent: IOmniboxItem[];
+  /**
+   * Commands matching the term.
+   */
   commands: IOmniboxItem[];
+  /**
+   * Workspace files matching the term.
+   */
   files: IOmniboxItem[];
+  /**
+   * Per-agent "Ask" rows carrying the term as a prompt.
+   */
   agents: IOmniboxItem[];
 }
 
+/**
+ * Inputs for {@link computeSections}.
+ */
 interface IComputeOptions {
+  /**
+   * Raw query text from the input.
+   */
   query: string;
+  /**
+   * The command registry used to look up and execute commands.
+   */
   commands: CommandRegistry;
   /**
-   * The command palette's items, whose labels are computed with each item's
-   * args — the only form in which entries like "Use Theme: …" exist.
+   * Palette items, whose labels are computed with each item's args — the only
+   * form in which entries like "Use Theme: …" exist.
    */
   paletteItems: ReadonlyArray<CommandPalette.IItem>;
+  /**
+   * The document registry used to pick file icons.
+   */
   docRegistry: DocumentRegistry;
+  /**
+   * The available agents; prompt-capable ones get "Ask" rows.
+   */
   agents: IAgent[];
+  /**
+   * Workspace-relative file paths to match against.
+   */
   files: string[];
   /**
    * Recently-used tracker; `null` disables the recent rows and recording.
    */
   recents: OmniboxRecents | null;
+  /**
+   * Translation bundle for row labels.
+   */
   trans: TranslationBundle;
 }
 
 const COMMAND_LIMIT = 7;
 const FILE_LIMIT = 10;
 
-/**
- * Prefixes that narrow the search to a single source: a leading `>` to
- * commands, a leading `/` to files (relative paths never start with `/`, so it
- * is unambiguous). Without a prefix, every source is searched.
- */
 const COMMAND_PREFIX = '>';
+// Unambiguous: workspace-relative paths never start with '/'.
 const FILE_PREFIX = '/';
 
 type Mode = 'all' | 'commands' | 'files';
 
 /**
  * Build the grouped result set for a query. A leading `>` searches only
- * commands and a leading `/` only files; otherwise commands and files are
- * fuzzy-matched and every prompt-capable agent is offered an "Ask" row
- * carrying the query as its prompt. An empty term yields the recently used
- * rows for the active mode instead (and the widget shows a hint when there
- * are none).
+ * commands, `/` only files; otherwise every prompt-capable agent also gets an
+ * "Ask" row carrying the query as its prompt. An empty term yields the
+ * recently used rows for the active mode.
  */
 export function computeSections(options: IComputeOptions): IOmniboxSections {
   const { query, commands, agents, trans } = options;
@@ -126,14 +150,12 @@ export function computeSections(options: IComputeOptions): IOmniboxSections {
     recent: [],
     commands: mode === 'files' ? [] : matchCommands(options, term),
     files: mode === 'commands' ? [] : matchFiles(options, term),
-    // Agents only in the unprefixed view; the prompt is the full typed query.
     agents: mode === 'all' ? buildAgentItems(commands, agents, term, trans) : []
   };
 }
 
 /**
- * Run a command and record the use on success, so failed commands never enter
- * the recents list.
+ * Run a command and record the use on success, so failures never enter the recents.
  */
 function executeCommand(
   commands: CommandRegistry,
@@ -151,9 +173,6 @@ function executeCommand(
     });
 }
 
-/**
- * Open a file and record the use on success.
- */
 function openFile(
   commands: CommandRegistry,
   recents: OmniboxRecents | null,
@@ -171,9 +190,8 @@ function openFile(
 
 /**
  * Read a command's label, visibility and caption, or `null` when the command
- * is missing, hidden, label-less, or its accessors throw (a command's
- * accessors can assume a context — e.g. an active notebook — the omnibox
- * doesn't provide).
+ * is missing, hidden, label-less, or its accessors throw (they can assume a
+ * context the omnibox doesn't provide).
  */
 function commandDisplay(
   commands: CommandRegistry,
@@ -196,10 +214,9 @@ function commandDisplay(
 
 /**
  * The recently used rows for the empty term: both kinds interleaved by
- * recency in the unprefixed view, or only the mode's kind under a bare `>` or
- * `/`. Commands that no longer resolve are dropped, as are files missing from
- * the loaded workspace listing (while the listing is still loading — or
- * unavailable — file entries are shown as recorded).
+ * recency, or only the mode's kind under a bare `>` or `/`. Unresolvable
+ * commands are dropped, as are files absent from the workspace listing once
+ * it loads.
  */
 function buildRecentItems(
   options: IComputeOptions,
@@ -250,11 +267,10 @@ function buildRecentItems(
 }
 
 /**
- * Match the query against the palette's items first — their labels carry each
- * item's args (one "Use Theme: …" per theme, one row per font-size key), which
- * a raw registry scan can never produce — then against registry commands the
- * palette doesn't present. Palette-covered ids are skipped in the registry
- * pass so a command never also surfaces under its argless label.
+ * Match palette items first — their labels carry per-item args (one "Use
+ * Theme: …" per theme), which a registry scan can never produce — then
+ * registry commands the palette doesn't present, skipping palette-covered ids
+ * so a command never also surfaces under its argless label.
  */
 function matchCommands(options: IComputeOptions, term: string): IOmniboxItem[] {
   const { commands, paletteItems, recents } = options;
@@ -269,8 +285,6 @@ function matchCommands(options: IComputeOptions, term: string): IOmniboxItem[] {
     let visible = true;
     let caption = '';
     try {
-      // An item's accessors can throw if the command assumes a context (e.g.
-      // an active notebook) the omnibox doesn't provide; skip those.
       label = item.label;
       visible = item.isVisible;
       caption = item.caption;
@@ -311,8 +325,6 @@ function matchCommands(options: IComputeOptions, term: string): IOmniboxItem[] {
     let visible = true;
     let caption = '';
     try {
-      // A command's accessors can throw if they assume a context (e.g. an
-      // active notebook) the omnibox doesn't provide; skip those.
       label = commands.label(id);
       visible = commands.isVisible(id);
       caption = commands.caption(id);
@@ -385,7 +397,7 @@ function buildAgentItems(
   const items: IOmniboxItem[] = [];
   for (const agent of agents) {
     // Agents without `promptArgs` can't take an inline prompt (the launcher
-    // would drop it), so they don't belong in an "Ask …" row.
+    // would drop it).
     if (agent.promptArgs === undefined) {
       continue;
     }

package/src/omnibox/recents.ts

@@ -1,46 +1,41 @@
 import type { IStateDB } from '@jupyterlab/statedb';
 import type { ReadonlyPartialJSONObject } from '@lumino/coreutils';
 
-/**
- * Kinds of omnibox results whose uses are recorded.
- */
 export type RecentKind = 'command' | 'file';
 
 /**
  * A single recorded use: a command that was run or a file that was opened.
  */
 interface IRecentEntry {
+  /**
+   * Whether the entry records a command run or a file opened.
+   */
   kind: RecentKind;
   /**
    * The command id, or the workspace-relative file path.
    */
   id: string;
   /**
-   * Arguments the command ran with, for palette-style entries whose label
-   * and behavior depend on them (e.g. one "Use Theme: …" per theme).
+   * Arguments the command ran with, for palette-style entries whose label and
+   * behavior depend on them.
    */
   args?: ReadonlyPartialJSONObject;
 }
 
 /**
- * Identity of an entry: two uses only match when kind, id and args all do,
- * so runs of one command with different args stay distinct entries.
+ * Identity of an entry: two uses only match when kind, id and args all do, so
+ * runs of one command with different args stay distinct.
  */
 function entryKey(entry: IRecentEntry): string {
   return `${entry.kind}\0${entry.id}\0${JSON.stringify(entry.args ?? null)}`;
 }
 
-/**
- * State database key the recents list is persisted under.
- */
 const STATE_KEY = 'xtralab:omnibox:recents';
 
 /**
- * A most-recently-used list of omnibox results, generic over the result kind
- * so commands and files (and future kinds) share one store. Entries are kept
- * most-recent-first, capped at `maxItems` per kind, and persisted through the
- * state database so they survive reloads. Without a state database the list
- * still works for the lifetime of the page.
+ * A most-recently-used list of omnibox results, most-recent-first, capped at
+ * `maxItems` per kind and persisted through the state database. Without a
+ * state database it still works for the lifetime of the page.
  */
 export class OmniboxRecents {
   constructor(options: OmniboxRecents.IOptions = {}) {
@@ -48,12 +43,14 @@ export class OmniboxRecents {
   }
 
   /**
-   * Maximum number of entries remembered per kind. Lowering it trims the list
-   * immediately; `0` disables recents entirely.
+   * Maximum entries kept per kind; lowering trims immediately, `0` disables recents.
    */
   get maxItems(): number {
     return this._maxItems;
   }
+  /**
+   * Set the maximum entries kept per kind.
+   */
   set maxItems(value: number) {
     const normalized = Math.max(0, Math.floor(value));
     if (normalized === this._maxItems) {
@@ -68,8 +65,7 @@ export class OmniboxRecents {
   }
 
   /**
-   * The recorded entries, most recent first — all of them, or only those of
-   * one kind.
+   * The recorded entries, most recent first, optionally filtered to one kind.
    */
   entries(kind?: RecentKind): IRecentEntry[] {
     return kind
@@ -78,8 +74,7 @@ export class OmniboxRecents {
   }
 
   /**
-   * Record a use of `id` (with the args it ran with, if any), moving it to
-   * the front of its kind's list.
+   * Record a use, moving the entry to the front of its kind's list.
    */
   touch(kind: RecentKind, id: string, args?: ReadonlyPartialJSONObject): void {
     const entry: IRecentEntry =
@@ -92,7 +87,7 @@ export class OmniboxRecents {
 
   /**
    * Load the persisted list. Entries recorded before the load completes stay
-   * at the front, ahead of the restored history.
+   * ahead of the restored history.
    */
   async restore(): Promise<void> {
     if (!this._state) {

package/src/omnibox/tokens.ts

@@ -1,10 +1,9 @@
 import { Token } from '@lumino/coreutils';
 
 /**
- * A launcher overlay that fuzzy-searches across multiple sources — workspace
- * files, JupyterLab commands — and routes a typed prompt to one of the
- * configured agents. Provided by `xtralab:omnibox` and consumed (optionally)
- * by the top-bar command bar, which opens it on click.
+ * A launcher overlay that fuzzy-searches workspace files and commands and
+ * routes a typed prompt to a configured agent. Provided by `xtralab:omnibox`;
+ * opened by the top-bar command bar.
  */
 export interface IOmnibox {
   /**
@@ -17,17 +16,13 @@ export interface IOmnibox {
   close(): void;
 }
 
-/**
- * DI token for {@link IOmnibox}. Provided by `xtralab:omnibox`; consumed by
- * `xtralab:command-bar` so the top-bar pill opens the omnibox.
- */
 export const IOmnibox = new Token<IOmnibox>(
   'xtralab:IOmnibox',
   'Opens the omnibox overlay that searches files and commands and prompts agents.'
 );
 
 /**
- * Command id that opens the omnibox (registered by `xtralab:omnibox`). Shared
- * here so the command bar can look up its keybinding and show a shortcut hint.
+ * Command id that opens the omnibox, shared so the command bar can look up
+ * its keybinding for the shortcut hint.
  */
 export const OMNIBOX_OPEN_COMMAND = 'xtralab:omnibox:open';

package/src/omnibox/widget.tsx

@@ -11,21 +11,15 @@ import { computeSections, IOmniboxItem } from './model';
 import { loadWorkspaceFiles } from './files';
 import type { OmniboxRecents } from './recents';
 
-/**
- * DOM id of the results listbox, referenced by the input's `aria-controls`.
- */
 const LIST_ID = 'jp-xtralab-Omnibox-list';
 
-/**
- * Stable DOM id for the result row at `index`, for `aria-activedescendant`.
- */
 function optionId(index: number): string {
   return `jp-xtralab-Omnibox-option-${index}`;
 }
 
 /**
  * Render `text` with the fuzzy-matched characters at `indices` wrapped in a
- * highlight span, leaving the rest as plain text.
+ * highlight span.
  */
 function renderHighlight(
   text: string,
@@ -125,13 +119,10 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
   );
   const hasResults = flat.length > 0;
 
-  // Reset the highlighted row whenever the result set changes, and keep the
-  // index in range when results shrink.
   React.useEffect(() => {
     setActive(current => (current < flat.length ? current : 0));
   }, [flat]);
 
-  // Keep the highlighted row scrolled into view as it moves.
   React.useEffect(() => {
     listRef.current
       ?.querySelector('.jp-mod-active')
@@ -139,8 +130,8 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
   }, [active, flat]);
 
   const dismiss = React.useCallback(() => {
-    // Defer so unmounting this React root (via onClose) never happens
-    // synchronously inside the event handler that triggered it.
+    // Defer so unmounting this React root never happens synchronously inside
+    // the event handler that triggered it.
     window.setTimeout(onClose, 0);
   }, [onClose]);
 
@@ -307,10 +298,8 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
 }
 
 /**
- * The omnibox overlay widget. Hosts {@link OmniboxComponent} in a React root
- * attached to `document.body`. It carries `jp-ThemedContainer` so JupyterLab's
- * theme CSS variables resolve outside the shell, and its own `jp-xtralab-Omnibox`
- * class for the overlay/panel styling (style/omnibox.css).
+ * The omnibox overlay widget, attached to `document.body`; `jp-ThemedContainer`
+ * makes JupyterLab's theme CSS variables resolve outside the shell.
  */
 export class OmniboxWidget extends ReactWidget {
   constructor(options: OmniboxWidget.IOptions) {
@@ -321,6 +310,9 @@ export class OmniboxWidget extends ReactWidget {
     this.addClass('jp-ThemedContainer');
   }
 
+  /**
+   * Render the omnibox overlay content.
+   */
   render(): JSX.Element {
     return <OmniboxComponent {...this._options} />;
   }
@@ -328,20 +320,23 @@ export class OmniboxWidget extends ReactWidget {
   private _options: OmniboxWidget.IOptions;
 }
 
-/**
- * A namespace for `OmniboxWidget` statics.
- */
 export namespace OmniboxWidget {
   /**
    * Construction options for {@link OmniboxWidget}.
    */
   export interface IOptions {
+    /**
+     * The command registry used to look up and execute commands.
+     */
     commands: CommandRegistry;
     /**
      * Snapshot of the command palette's items, read once when the overlay
      * opens; empty when the palette isn't available.
      */
     paletteItems: ReadonlyArray<CommandPalette.IItem>;
+    /**
+     * The document registry used to pick file icons.
+     */
     docRegistry: DocumentRegistry;
     /**
      * Snapshot of the available agents, read once when the overlay opens.