chore: add typedoc to TableViewProvider; standardize TableMediator te…

…st layout Signed-off-by: Trae Yelovich <[email protected]>
zowe · Jul 30, 2024 · 1da2895 · 1da2895
1 parent 82f3032
commit 1da2895
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 34 deletions.
diff --git a/packages/zowe-explorer-api/__tests__/__unit__/vscode/ui/utils/TableMediator.unit.test.ts b/packages/zowe-explorer-api/__tests__/__unit__/vscode/ui/utils/TableMediator.unit.test.ts
@@ -39,46 +39,48 @@ function createGlobalMocks() {
     };
 }
 
-describe("TableMediator::getInstance", () => {
-    it("returns an instance of TableMediator", () => {
-        expect(TableMediator.getInstance()).toBeInstanceOf(TableMediator);
+describe("TableMediator", () => {
+    describe("getInstance", () => {
+        it("returns an instance of TableMediator", () => {
+            expect(TableMediator.getInstance()).toBeInstanceOf(TableMediator);
+        });
     });
-});
 
-describe("TableMediator::addTable", () => {
-    it("adds the given table object to its internal map", () => {
-        const globalMocks = createGlobalMocks();
-        TableMediator.getInstance().addTable(globalMocks.table);
-        expect((TableMediator.getInstance() as any).tables.get(globalMocks.table.getId())).toBe(globalMocks.table);
-        (TableMediator.getInstance() as any).tables = new Map();
+    describe("addTable", () => {
+        it("adds the given table object to its internal map", () => {
+            const globalMocks = createGlobalMocks();
+            TableMediator.getInstance().addTable(globalMocks.table);
+            expect((TableMediator.getInstance() as any).tables.get(globalMocks.table.getId())).toBe(globalMocks.table);
+            (TableMediator.getInstance() as any).tables = new Map();
+        });
     });
-});
 
-describe("TableMediator::getTable", () => {
-    it("retrieves the table by ID using its internal map", () => {
-        const globalMocks = createGlobalMocks();
-        const tableId = globalMocks.table.getId();
-        TableMediator.getInstance().addTable(globalMocks.table);
-        expect(TableMediator.getInstance().getTable(tableId)).toBe(globalMocks.table);
-        (TableMediator.getInstance() as any).tables = new Map();
+    describe("getTable", () => {
+        it("retrieves the table by ID using its internal map", () => {
+            const globalMocks = createGlobalMocks();
+            const tableId = globalMocks.table.getId();
+            TableMediator.getInstance().addTable(globalMocks.table);
+            expect(TableMediator.getInstance().getTable(tableId)).toBe(globalMocks.table);
+            (TableMediator.getInstance() as any).tables = new Map();
+        });
     });
-});
 
-describe("TableMediator::removeTable", () => {
-    it("removes a table view from its internal map", () => {
-        const globalMocks = createGlobalMocks();
-        const tableId = globalMocks.table.getId();
-        TableMediator.getInstance().addTable(globalMocks.table);
-        expect(TableMediator.getInstance().removeTable(globalMocks.table)).toBe(true);
-        expect((TableMediator.getInstance() as any).tables.get(globalMocks.table.getId())).toBe(undefined);
-        expect(TableMediator.getInstance().getTable(tableId)).toBe(undefined);
-    });
+    describe("removeTable", () => {
+        it("removes a table view from its internal map", () => {
+            const globalMocks = createGlobalMocks();
+            const tableId = globalMocks.table.getId();
+            TableMediator.getInstance().addTable(globalMocks.table);
+            expect(TableMediator.getInstance().removeTable(globalMocks.table)).toBe(true);
+            expect((TableMediator.getInstance() as any).tables.get(globalMocks.table.getId())).toBe(undefined);
+            expect(TableMediator.getInstance().getTable(tableId)).toBe(undefined);
+        });
 
-    it("returns false if the table instance does not exist in the map", () => {
-        const globalMocks = createGlobalMocks();
-        globalMocks.createWebviewPanelMock.mockReturnValueOnce(globalMocks.mockPanel as any);
-        const table2 = new TableBuilder(globalMocks.extensionContext as any).build();
-        TableMediator.getInstance().addTable(globalMocks.table);
-        expect(TableMediator.getInstance().removeTable(table2)).toBe(false);
+        it("returns false if the table instance does not exist in the map", () => {
+            const globalMocks = createGlobalMocks();
+            globalMocks.createWebviewPanelMock.mockReturnValueOnce(globalMocks.mockPanel as any);
+            const table2 = new TableBuilder(globalMocks.extensionContext as any).build();
+            TableMediator.getInstance().addTable(globalMocks.table);
+            expect(TableMediator.getInstance().removeTable(table2)).toBe(false);
+        });
     });
 });
diff --git a/packages/zowe-explorer-api/src/vscode/ui/TableViewProvider.ts b/packages/zowe-explorer-api/src/vscode/ui/TableViewProvider.ts
@@ -12,6 +12,30 @@
 import { CancellationToken, WebviewView, WebviewViewProvider, WebviewViewResolveContext } from "vscode";
 import { Table } from "./TableView";
 
+/**
+ * View provider class for rendering table views in the "Zowe Resources" panel.
+ * Registered during initialization of Zowe Explorer.
+ *
+ * @remarks
+ * ## Usage
+ *
+ * ### Setting the current table view
+ *
+ * Use the {@link setTableView} function to set a table view for the "Zowe Resources" panel.
+ * _Note_ that setting another table view on the view provider will dispose of the last table instance that was provided.
+ *
+ * ### Getting the current table view
+ *
+ * Use the {@link getTableView} function to get the current table view in the "Zowe Resources" panel.
+ *
+ * ### resolveWebviewView
+ *
+ * VS Code uses this function to resolve the instance of the table view to render. **Please do not use this function directly** -
+ * use {@link setTableView} instead to provide the table view.
+ *
+ * Calling the function directly will interfere with the intended behavior of
+ * the "Zowe Resources" panel and is therefore not supported.
+ */
 export class TableViewProvider implements WebviewViewProvider {
     private view?: WebviewView;
     private tableView: Table.Instance = null;
@@ -20,6 +44,10 @@ export class TableViewProvider implements WebviewViewProvider {
 
     private constructor() {}
 
+    /**
+     * Retrieve the singleton instance of the TableViewProvider.
+     * @returns the TableViewProvider instance used by Zowe Explorer
+     */
     public static getInstance(): TableViewProvider {
         if (!this.instance) {
             this.instance = new TableViewProvider();
@@ -28,6 +56,10 @@ export class TableViewProvider implements WebviewViewProvider {
         return this.instance;
     }
 
+    /**
+     * Provide a table view to display in the "Zowe Resources" view.
+     * @param tableView The table view to prepare for rendering
+     */
     public setTableView(tableView: Table.Instance | null): void {
         if (this.tableView != null) {
             this.tableView.dispose();
@@ -46,10 +78,19 @@ export class TableViewProvider implements WebviewViewProvider {
         }
     }
 
+    /**
+     * Retrieve the current table view for the "Zowe Resources" panel, if one exists.
+     */
     public getTableView(): Table.View {
         return this.tableView;
     }
 
+    /**
+     * VS Code internal function used to resolve the webview view from the view provider.
+     * @param webviewView The webview view object for the panel
+     * @param context Additional context for the webview view
+     * @param token (unused) cancellation token for the webview view resolution process
+     */
     public resolveWebviewView(
         webviewView: WebviewView,
         context: WebviewViewResolveContext<unknown>,