docs: fix facade api jsdoc inconsistencies (#7191)

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

@@ -42,6 +42,7 @@ export class FHooks extends FBase {
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
      */
     onStarting(callback: () => void): IDisposable {
@@ -50,6 +51,7 @@ export class FHooks extends FBase {
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
      */
     onReady(callback: () => void): IDisposable {
@@ -58,6 +60,7 @@ export class FHooks extends FBase {
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
      */
     onRendered(callback: () => void): IDisposable {
@@ -66,6 +69,7 @@ export class FHooks extends FBase {
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
      */
     onSteady(callback: () => void): IDisposable {
@@ -74,6 +78,7 @@ export class FHooks extends FBase {
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeUndo, (event) => {})` as instead
      */
     onBeforeUndo(callback: (action: IUndoRedoItem) => void): IDisposable {
@@ -92,6 +97,7 @@ export class FHooks extends FBase {
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated use `univerAPI.addEvent(univerAPI.Event.Undo, (event) => {})` as instead
      */
     onUndo(callback: (action: IUndoRedoItem) => void): IDisposable {
@@ -110,6 +116,7 @@ export class FHooks extends FBase {
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeRedo, (event) => {})` as instead
      */
     onBeforeRedo(callback: (action: IUndoRedoItem) => void): IDisposable {
@@ -128,6 +135,7 @@ export class FHooks extends FBase {
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated use `univerAPI.addEvent(univerAPI.Event.Redo, (event) => {})` as instead
      */
     onRedo(callback: (action: IUndoRedoItem) => void): IDisposable {

packages/docs/src/facade/f-document.ts

@@ -393,6 +393,7 @@ export class FDocument extends FBaseInitialable {
     /**
      * Append a plain-text paragraph at the end of the body.
      * @param {string} text The paragraph text. Defaults to an empty paragraph.
+     * @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
      * @returns {FDocumentParagraph} The appended paragraph wrapper.
      * @example
      * ```ts

packages/engine-formula/src/facade/f-formula.ts

@@ -205,6 +205,8 @@ export class FFormula extends FBase {
 
     /**
      * @deprecated Use `onCalculationResultApplied` instead.
+     * @param {number} [timeout] The timeout in milliseconds. Defaults to 30000.
+     * @returns {Promise<boolean>} Whether computing completed before timeout.
      */
     whenComputingCompleteAsync(timeout?: number): Promise<boolean> {
         const gcss = this._injector.get(GlobalComputingStatusService);
@@ -218,6 +220,7 @@ export class FFormula extends FBase {
 
     /**
      * @deprecated Use `onCalculationResultApplied` instead.
+     * @returns {Promise<void>} A promise that resolves when calculation ends.
      */
     onCalculationEnd(): Promise<void> {
         return new Promise((resolve, reject) => {
@@ -439,11 +442,11 @@ export class FFormula extends FBase {
      * dependency-calculation command for the given unit, sheet, and cell location,
      * and returns the computed dependency tree when the calculation is completed.
      *
-     * @param param The target cell location:
-     *   - `unitId`  The workbook ID.
-     *   - `sheetId` The sheet ID.
-     *   - `row`     The zero-based row index.
-     *   - `column`  The zero-based column index.
+     * @param {object} param The target cell location.
+     * @param {string} param.unitId The workbook ID.
+     * @param {string} param.sheetId The sheet ID.
+     * @param {number} param.row The zero-based row index.
+     * @param {number} param.column The zero-based column index.
      *
      * @param {number} [timeout]
      *        Optional timeout in milliseconds. If no result is received within this
@@ -749,6 +752,7 @@ export class FFormula extends FBase {
      * ```
      *
      * @param formulaString The formula string to parse (with or without leading `=`)
+     * @param unitId The workbook unit id used to resolve defined names and tables.
      * @returns A formula expression tree describing the hierarchical structure of the formula
      */
     getFormulaExpressTree(formulaString: string, unitId: string): IExprTreeNode | null {

packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts

@@ -1108,14 +1108,7 @@ class ConditionalFormatDataBarRuleBuilder extends ConditionalFormatRuleBaseBuild
 
     /**
      * Set data bar rule.
-     * @param {{
-     *         min: IValueConfig;
-     *         max: IValueConfig;
-     *         isGradient?: boolean;
-     *         positiveColor: string;
-     *         nativeColor: string;
-     *         isShowValue?: boolean;
-     *     }} config - The data bar rule settings.
+     * @param {object} config - The data bar rule settings.
      * @param {IValueConfig} config.min - The minimum value for the data bar.
      * @param {IValueConfig} config.max - The maximum value for the data bar.
      * @param {boolean} [config.isGradient] - Whether the data bar is gradient.
@@ -1606,14 +1599,7 @@ export class FConditionalFormattingBuilder {
 
     /**
      * Set data bar rule.
-     * @param {{
-     *         min: IValueConfig;
-     *         max: IValueConfig;
-     *         isGradient?: boolean;
-     *         positiveColor: string;
-     *         nativeColor: string;
-     *         isShowValue?: boolean;
-     *     }} config - The data bar rule settings.
+     * @param {object} config - The data bar rule settings.
      * @param {IValueConfig} config.min - The minimum value for the data bar.
      * @param {IValueConfig} config.max - The maximum value for the data bar.
      * @param {boolean} [config.isGradient] - Whether the data bar is gradient.

packages/sheets-drawing/src/facade/f-over-grid-image.ts

@@ -67,8 +67,7 @@ function convertSheetImageToFOverGridImage(sheetImage: ISheetImage, skeleton: Sp
 /**
  * Convert the FOverGridImage to a ISheetImage
  * @param {IFOverGridImage} fOverGridImage The FOverGridImage
- * @param {ISheetSelectionRenderService} selectionRenderService The selection render service
- * @param {SheetSkeletonManagerService} sheetSkeletonManagerService The skeleton manager service
+ * @param {SheetSkeletonService} sheetSkeletonService The sheet skeleton service
  * @returns {ISheetImage} The ISheetImage {@link ISheetImage}
  */
 function convertFOverGridImageToSheetImage(fOverGridImage: IFOverGridImage, sheetSkeletonService: SheetSkeletonService): ISheetImage {
@@ -222,6 +221,12 @@ export class FOverGridImageBuilder {
         return this;
     }
 
+    /**
+     * Set the source of the image. The source type defaults to URL.
+     * @param {string} source - The source of the image
+     * @returns {FOverGridImageBuilder} The `FOverGridImageBuilder` for chaining
+     */
+    setSource(source: string): FOverGridImageBuilder;
     /**
      * Set the source of the image.
      * @param {string} source - The source of the image
@@ -242,7 +247,6 @@ export class FOverGridImageBuilder {
      * fWorksheet.insertImages([image]);
      * ```
      */
-    setSource(source: string): FOverGridImageBuilder;
     setSource(source: string, sourceType?: ImageSourceType): FOverGridImageBuilder;
     setSource(source: string, sourceType?: ImageSourceType): FOverGridImageBuilder {
         const sourceTypeVal = sourceType ?? ImageSourceType.URL;

packages/sheets-thread-comment/src/facade/f-thread-comment.ts

@@ -422,7 +422,8 @@ export class FThreadComment {
     }
 
     /**
-     * @deprecated use `getRichText` as instead
+     * @deprecated Use `getRichText` instead.
+     * @returns {IDocumentBody} The comment content.
      */
     getContent(): IDocumentBody {
         return this._thread.text;
@@ -474,14 +475,17 @@ export class FThreadComment {
     }
 
     /**
-     * @deprecated use `deleteAsync` as instead.
+     * @deprecated Use `deleteAsync` instead.
+     * @returns {Promise<boolean>} Whether the comment is deleted successfully.
      */
     delete(): Promise<boolean> {
         return this.deleteAsync();
     }
 
     /**
-     * @deprecated use `updateAsync` as instead
+     * @deprecated Use `updateAsync` instead.
+     * @param {IDocumentBody} content The new content of the comment.
+     * @returns {Promise<boolean>} Whether the comment is updated successfully.
      */
     async update(content: IDocumentBody): Promise<boolean> {
         return this.updateAsync(content);
@@ -535,7 +539,9 @@ export class FThreadComment {
     }
 
     /**
-     * @deprecated use `resolveAsync` as instead
+     * @deprecated Use `resolveAsync` instead.
+     * @param {boolean} [resolved] Whether the comment is resolved.
+     * @returns {Promise<boolean>} Set the comment to resolved or not operation result.
      */
     resolve(resolved?: boolean): Promise<boolean> {
         return this.resolveAsync(resolved);

packages/sheets-thread-comment/src/facade/f-univer.ts

@@ -310,6 +310,7 @@ export class FUniverSheetsThreadCommentMixin extends FUniver implements IFUniver
 
     /**
      * @ignore
+     * @returns {FTheadCommentBuilder} The thread comment builder.
      */
     override newTheadComment(comment?: IThreadComment): FTheadCommentBuilder {
         return new FTheadCommentBuilder(comment);

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

@@ -121,6 +121,7 @@ export class FWorkbookSheetsThreadCommentMixin extends FWorkbook implements IFWo
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated
      */
     override onThreadCommentChange(callback: (commentUpdate: CommentUpdate) => void | false): IDisposable {
@@ -131,6 +132,7 @@ export class FWorkbookSheetsThreadCommentMixin extends FWorkbook implements IFWo
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated
      */
     override onBeforeAddThreadComment(callback: (params: IAddCommentCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable {
@@ -149,6 +151,7 @@ export class FWorkbookSheetsThreadCommentMixin extends FWorkbook implements IFWo
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated
      */
     override onBeforeUpdateThreadComment(callback: (params: IUpdateCommentCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable {
@@ -167,6 +170,7 @@ export class FWorkbookSheetsThreadCommentMixin extends FWorkbook implements IFWo
 
     /**
      * @param callback
+     * @returns {IDisposable} A disposable used to remove the listener.
      * @deprecated
      */
     override onBeforeDeleteThreadComment(callback: (params: IDeleteCommentCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable {

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

@@ -108,6 +108,7 @@ export class FWorksheetCommentMixin extends FWorksheet implements IFWorksheetCom
     /**
      * Subscribe to comment events.
      * @param callback Callback function, param contains comment info and target cell.
+     * @returns {IDisposable} A disposable used to remove the listener.
      */
     onCommented(callback: (params: IAddCommentCommandParams) => void): IDisposable {
         const commandService = this._injector.get(ICommandService);

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

@@ -146,6 +146,7 @@ export class FWorkbook extends FBaseInitialable {
     /**
      * Set the name of the workbook.
      * @param {string} name The new name of the workbook.
+     * @returns {FWorkbook} The current FWorkbook instance for chaining.
      * @example
      * ```ts
      * // The code below sets the name of the workbook
@@ -887,7 +888,6 @@ export class FWorkbook extends FBaseInitialable {
     /**
      * Insert a defined name by builder param.
      * @param {ISetDefinedNameMutationParam} param The param to insert the defined name
-     * @returns {void}
      * @example
      * ```ts
      * // The code below inserts a defined name by builder param
@@ -907,7 +907,6 @@ export class FWorkbook extends FBaseInitialable {
     /**
      * Update the defined name with the given name.
      * @param {ISetDefinedNameMutationParam} param The param to insert the defined name
-     * @returns {void}
      * @example
      * ```ts
      * // The code below updates the defined name with the given name
@@ -990,7 +989,6 @@ export class FWorkbook extends FBaseInitialable {
     /**
      * Register a custom range theme style.
      * @param {RangeThemeStyle} rangeThemeStyle The range theme style to register
-     * @returns {void}
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1014,7 +1012,6 @@ export class FWorkbook extends FBaseInitialable {
     /**
      * Unregister a custom range theme style.
      * @param {string} themeName The name of the theme to unregister
-     * @returns {void}
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();

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

@@ -199,6 +199,8 @@ export class FRangePermission extends FBase {
 
     /**
      * List all protection rules that intersect with the current range.
+     * @param {object} [options] Options for listing protection rules.
+     * @param {boolean} [options.ignoreCollaborators] Whether to skip fetching collaborators for performance.
      * @returns {Promise<FRangeProtectionRule[]>} Array of protection rules.
      * @example
      * ```ts

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

@@ -768,6 +768,8 @@ export class FWorksheetPermission extends FBase {
 
     /**
      * List all range protection rules for the worksheet.
+     * @param {object} [options] Options for listing range protection rules.
+     * @param {boolean} [options.ignoreCollaborators] Whether to skip fetching collaborators for performance.
      * @returns {Promise<FRangeProtectionRule[]>} Array of protection rules.
      * @example
      * ```ts

packages/sheets/src/facade/permission/util.ts

@@ -50,6 +50,9 @@ export function determineScope(editState: EditStateEnum, viewState: ViewStateEnu
 /**
  * Check if there are no range protection rules for the given unit and subunit when removing a range protection rule.
  * If there are no rules left, also remove the associated worksheet protection and update the permission points accordingly.
+ * @param {Injector} injector The injector used to resolve permission services.
+ * @param {string} unitId The workbook unit id.
+ * @param {string} subUnitId The worksheet subunit id.
  */
 export function handleWorksheetRangePermissionIsEmpty(injector: Injector, unitId: string, subUnitId: string): void {
     const rangeProtectionRuleModel = injector.get(RangeProtectionRuleModel);
@@ -72,6 +75,14 @@ export function handleWorksheetRangePermissionIsEmpty(injector: Injector, unitId
 
 /**
  * Get the list of range protection rules for a specific worksheet or range, and convert them to FRangeProtectionRule instances.
+ * @param {Injector} injector The injector used to resolve permission services.
+ * @param {string} unitId The workbook unit id.
+ * @param {string} subUnitId The worksheet subunit id.
+ * @param {object} options Options for listing range protection rules.
+ * @param {FWorksheet} options.worksheet The worksheet facade used to convert ranges.
+ * @param {FRange} [options.specificRange] Optional range used to filter rules.
+ * @param {boolean} [options.ignoreCollaborators] Whether to skip fetching collaborators for performance.
+ * @returns {Promise<FRangeProtectionRule[]>} The range protection rules.
  */
 export async function getListRangeProtectionRules(
     injector: Injector,

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

@@ -192,6 +192,7 @@ export class FMenu extends FMenuBase {
 
     /**
      * @ignore
+     * @returns The generated menu schema.
      */
     __getSchema(): { [key: string]: MenuSchemaType } {
         this._commandToRegister.forEach((command, id) => {
@@ -326,6 +327,7 @@ export class FSubmenu extends FMenuBase {
 
     /**
      * @ignore
+     * @returns The generated submenu schema.
      */
     __getSchema(): { [key: string]: MenuSchemaType } {
         const schema: { [key: string]: MenuSchemaType } = {};