docs(core): add description to Facade API (#4555)

packages/core/src/facade/f-univer.ts

@@ -41,6 +41,9 @@ import { FUserManager } from './f-usermanager';
 import { FUtil } from './f-util';
 
 /**
+ * The root Facade API object to interact with Univer. Please use `newAPI` static method
+ * to create a new instance.
+ *
  * @hideconstructor
  */
 export class FUniver extends FBaseInitialable {

packages/network/src/facade/f-network.ts

@@ -20,6 +20,10 @@ import { FBase, Inject, Injector } from '@univerjs/core';
 import { HTTPService } from '@univerjs/network';
 
 /**
+ * This Facade provides a set of methods to make HTTP requests. You should not
+ * create an instance of this class directly, instead, use `getNetwork` of
+ * {@link FUniver} instead.
+ *
  * @hideconstructor
  */
 export class FNetwork extends FBase {
@@ -31,50 +35,50 @@ export class FNetwork extends FBase {
     }
 
     /**
-     * Send GET request to the server.
-     * @param url The requested URL
-     * @param params Query parameters
-     * @returns Network response
+     * Send a GET request to the server.
+     * @param {string} url - The requested URL.
+     * @param {IRequestParams} [params] - Query parameters.
+     * @returns {Promise<HTTPResponse>} Network response.
      */
     get<T>(url: string, params?: IRequestParams): Promise<HTTPResponse<T>> {
         return this._httpService.get(url, params) as Promise<HTTPResponse<T>>; ;
     }
 
     /**
-     * Send POST request to the server.
-     * @param url The requested URL
-     * @param params Query parameters
-     * @returns Network response
+     * Send a POST request to the server.
+     * @param {string} url - The requested URL.
+     * @param {IPostRequestParams} [params] - Query parameters.
+     * @returns {Promise<HTTPResponse>} Network response.
      */
     post<T>(url: string, params?: IPostRequestParams): Promise<HTTPResponse<T>> {
         return this._httpService.post(url, params) as Promise<HTTPResponse<T>>; ;
     }
 
     /**
-     * Send PUT request to the server.
-     * @param url The requested URL
-     * @param params Query parameters
-     * @returns Network response
+     * Send a PUT request to the server.
+     * @param {string} url - The requested URL
+     * @param {IPostRequestParams} [params] - Query parameters
+     * @returns {Promise<HTTPResponse>} Network response
      */
     put<T>(url: string, params?: IPostRequestParams): Promise<HTTPResponse<T>> {
         return this._httpService.put(url, params) as Promise<HTTPResponse<T>>; ;
     }
 
     /**
      * Send DELETE request to the server.
-     * @param url The requested URL
-     * @param params Query parameters
-     * @returns Network response
+     * @param {string} url - The requested URL
+     * @param {IRequestParams} [params] - Query parameters
+     * @returns {Promise<HTTPResponse>} Network response
      */
     delete<T>(url: string, params?: IRequestParams): Promise<HTTPResponse<T>> {
         return this._httpService.delete(url, params) as Promise<HTTPResponse<T>>; ;
     }
 
     /**
      * Send PATCH request to the server.
-     * @param url The requested URL
-     * @param params Query parameters
-     * @returns Network response
+     * @param {string} url - The requested URL
+     * @param {IPostRequestParams} [params] - Query parameters
+     * @returns {Promise<HTTPResponse>} Network response
      */
     patch<T>(url: string, params?: IPostRequestParams): Promise<HTTPResponse<T>> {
         return this._httpService.patch(url, params) as Promise<HTTPResponse<T>>;
@@ -83,10 +87,10 @@ export class FNetwork extends FBase {
     /**
      * Request for a stream of server-sent events. Instead of a single response, the server sends a stream of responses,
      * Univer wraps the stream in an [`Observable`](https://rxjs.dev/guide/observable) which you can call `subscribe` on.
-     * @param method HTTP request method
-     * @param url The requested URL
-     * @param params Query parameters
-     * @returns An observable that emits the network response
+     * @param {HTTPRequestMethod} method - HTTP request method
+     * @param {string} url - The requested URL
+     * @param {IPostRequestParams} [params] - params Query parameters
+     * @returns {Observable<HTTPEvent>} An observable that emits the network response.
      */
     getSSE<T>(
         method: HTTPRequestMethod,

packages/network/src/facade/f-univer.ts

@@ -17,6 +17,7 @@
 import { FUniver } from '@univerjs/core';
 import { FNetwork } from './f-network';
 
+/** @ignore */
 interface IFUniverNetworkMixin {
     /**
      * Get the network API of Univer, with the help of which you can send HTTP requests.

packages/sheets-filter/src/facade/f-worksheet.ts

@@ -20,6 +20,7 @@ import { SheetsFilterService } from '@univerjs/sheets-filter';
 import { FWorksheet } from '@univerjs/sheets/facade';
 import { FFilter } from './f-filter';
 
+/** @ignore */
 export interface IFWorksheetFilter {
     /**
      * Get the filter for the current worksheet.

packages/sheets-sort/src/facade/f-worksheet.ts

@@ -20,6 +20,7 @@ import { type IRange, RANGE_TYPE } from '@univerjs/core';
 import { SortRangeCommand, SortType } from '@univerjs/sheets-sort';
 import { FWorksheet } from '@univerjs/sheets/facade';
 
+/** @ignore */
 export interface IFWorksheetSort {
     /**
      * Sort the worksheet by the specified column.

packages/sheets-ui/src/facade/f-workbook.ts

@@ -26,6 +26,7 @@ import { FWorkbook } from '@univerjs/sheets/facade';
 import { type IDialogPartMethodOptions, IDialogService, type ISidebarMethodOptions, ISidebarService, KeyCode } from '@univerjs/ui';
 import { filter } from 'rxjs';
 
+/** @ignore */
 export interface IFWorkbookSheetsUIMixin {
     /**
      * Open a sidebar.

packages/sheets-ui/src/facade/f-worksheet.ts

@@ -23,6 +23,7 @@ import { IRenderManagerService, SHEET_VIEWPORT_KEY, sheetContentViewportKeys } f
 import { ChangeZoomRatioCommand, SetWorksheetColAutoWidthCommand, SheetScrollManagerService, SheetSkeletonManagerService, SheetsScrollRenderController } from '@univerjs/sheets-ui';
 import { FWorksheet } from '@univerjs/sheets/facade';
 
+/** @ignore */
 export interface IFWorksheetSkeletonMixin {
     /**
      * Refresh the canvas.

packages/sheets/src/facade/f-range.ts

@@ -28,6 +28,9 @@ export type FontStyle = 'normal' | 'italic';
 export type FontWeight = 'normal' | 'bold';
 
 /**
+ * Represents a range of cells in a sheet. You can call methods on this Facade API object
+ * to read contents or manipulate the range.
+ *
  * @hideconstructor
  */
 export class FRange extends FBaseInitialable {

packages/sheets/src/facade/f-selection.ts

@@ -24,7 +24,8 @@ import { FWorkbook } from './f-workbook';
 import { FWorksheet } from './f-worksheet';
 
 /**
- * @description Represents the active selection in the sheet.
+ * Represents the active selection in the sheet.
+ *
  * @example
  * ```ts
  * const fWorkbook = univerAPI.getActiveWorkbook()

packages/sheets/src/facade/f-workbook.ts

@@ -27,6 +27,7 @@ import { FRange } from './f-range';
 import { FWorksheet } from './f-worksheet';
 
 /**
+ * Facade API object bounded to a workbook. It provides a set of methods to interact with the workbook.
  * @hideconstructor
  */
 export class FWorkbook extends FBaseInitialable {

packages/sheets/src/facade/f-worksheet.ts

@@ -32,7 +32,7 @@ interface IFacadeClearOptions {
 }
 
 /**
- * Represents a worksheet facade api instance. Which provides a set of methods to interact with the worksheet.
+ * A Facade API object bounded to a worksheet. It provides a set of methods to interact with the worksheet.
  * @hideconstructor
  */
 export class FWorksheet extends FBaseInitialable {

packages/ui/src/facade/f-menu-builder.ts

@@ -76,6 +76,7 @@ export interface IFacadeSubmenuItem {
     order?: number;
 }
 
+/** @ignore */
 type FAllMenu = FMenu | FSubmenu;
 
 /**
@@ -131,9 +132,14 @@ abstract class FMenuBase extends FBase {
 }
 
 /**
- * This is a build for adding a menu to Univer. Please notice that until the `appendTo` method is called,
- * the menu item is not added to the UI. Please note that this menu cannot have submenus. If you want to
- * have submenus, please use `FSubmenu`.
+ * This is the builder for adding a menu to Univer. You shall never construct this
+ * class by yourself. Instead, call `createMenu` of {@link FUniver} to create a instance.
+ *
+ * Please notice that until the `appendTo` method is called, the menu item is not added to the UI.
+ *
+ * Please note that this menu cannot have submenus. If you want to
+ * have submenus, please use {@link FSubmenu}.
+ *
  * @hideconstructor
  */
 export class FMenu extends FMenuBase {
@@ -194,6 +200,12 @@ export class FMenu extends FMenuBase {
 }
 
 /**
+ * This is the builder for add a menu that can contains submenus to Univer. You shall
+ * never construct this class by yourself. Instead, call `createSubmenu` of {@link FUniver} to
+ * create a instance.
+ *
+ * Please notice that until the `appendTo` method is called, the menu item is not added to the UI.
+ *
  * @hideconstructor
  */
 export class FSubmenu extends FMenuBase {

packages/ui/src/facade/f-shortcut.ts

@@ -20,6 +20,7 @@ import { FBase, Inject, Injector } from '@univerjs/core';
 import { IShortcutService } from '@univerjs/ui';
 
 /**
+ * The Facade API object to handle shortcuts in Univer
  * @hideconstructor
  */
 export class FShortcut extends FBase {
@@ -32,17 +33,44 @@ export class FShortcut extends FBase {
         super();
     }
 
-    enableShortcut(): void {
+    /**
+     * Enable shortcuts of Univer.
+     * @returns {FShortcut} The Facade API instance itself for chaining.
+     */
+    enableShortcut(): this {
         this._forceEscapeDisposable?.dispose();
         this._forceEscapeDisposable = null;
+        return this;
     }
 
-    disableShortcut(): void {
+    /**
+     * Disable shortcuts of Univer.
+     * @returns {FShortcut} The Facade API instance itself for chaining.
+     */
+    disableShortcut(): this {
         if (!this._forceEscapeDisposable) {
             this._forceEscapeDisposable = this._shortcutService.forceEscape();
         }
+
+        return this;
     }
 
+    /**
+     * Dispatch a KeyboardEvent to the shortcut service and return the matched shortcut item.
+     * @param {KeyboardEvent} e - The KeyboardEvent to dispatch.
+     * @returns {IShortcutItem<object> | undefined} The matched shortcut item.
+     *
+     * @example
+     * ```typescript
+     * const fShortcut = univerAPI.getShortcut();
+     * const pseudoEvent = new KeyboardEvent('keydown', { key: 's', ctrlKey: true });
+     * const ifShortcutItem = fShortcut.dispatchShortcutEvent(pseudoEvent);
+     * if (ifShortcutItem) {
+     *   const commandId = ifShortcutItem.id;
+     *   // Do something with the commandId.
+     * }
+     * ```
+     */
     dispatchShortcutEvent(e: KeyboardEvent): IShortcutItem<object> | undefined {
         return this._shortcutService.dispatch(e);
     }