Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

docs: fix facade api jsdoc inconsistencies (#7191)

白熱b8f7f6ff64ee
diff --git a/packages/core/src/facade/f-hooks.ts b/packages/core/src/facade/f-hooks.ts
index cc239c95b1..04416ad4ff 100644
--- a/packages/core/src/facade/f-hooks.ts
+++ b/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 {
diff --git a/packages/docs/src/facade/f-document.ts b/packages/docs/src/facade/f-document.ts
index ab0e5e2a5c..08288d8d40 100644
--- a/packages/docs/src/facade/f-document.ts
+++ b/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
diff --git a/packages/engine-formula/src/facade/f-formula.ts b/packages/engine-formula/src/facade/f-formula.ts
index fe28e07b8d..50bf244ea2 100644
--- a/packages/engine-formula/src/facade/f-formula.ts
+++ b/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 {
diff --git a/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts b/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts
index 94778ba1f5..e19b94b93d 100644
--- a/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts
+++ b/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.
diff --git a/packages/sheets-drawing/src/facade/f-over-grid-image.ts b/packages/sheets-drawing/src/facade/f-over-grid-image.ts
index 93388af853..2589166b0b 100644
--- a/packages/sheets-drawing/src/facade/f-over-grid-image.ts
+++ b/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;
diff --git a/packages/sheets-thread-comment/src/facade/f-thread-comment.ts b/packages/sheets-thread-comment/src/facade/f-thread-comment.ts
index 9e11a1f939..0eeae4f5f7 100644
--- a/packages/sheets-thread-comment/src/facade/f-thread-comment.ts
+++ b/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);
diff --git a/packages/sheets-thread-comment/src/facade/f-univer.ts b/packages/sheets-thread-comment/src/facade/f-univer.ts
index 807d073068..c965e0badc 100644
--- a/packages/sheets-thread-comment/src/facade/f-univer.ts
+++ b/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);
diff --git a/packages/sheets-thread-comment/src/facade/f-workbook.ts b/packages/sheets-thread-comment/src/facade/f-workbook.ts
index 2b4a2adb82..059bc4d83f 100644
--- a/packages/sheets-thread-comment/src/facade/f-workbook.ts
+++ b/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 {
diff --git a/packages/sheets-thread-comment/src/facade/f-worksheet.ts b/packages/sheets-thread-comment/src/facade/f-worksheet.ts
index 5f056c86da..4badae5652 100644
--- a/packages/sheets-thread-comment/src/facade/f-worksheet.ts
+++ b/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);
diff --git a/packages/sheets/src/facade/f-workbook.ts b/packages/sheets/src/facade/f-workbook.ts
index b6a9cc71d6..ad3df1927f 100644
--- a/packages/sheets/src/facade/f-workbook.ts
+++ b/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();
diff --git a/packages/sheets/src/facade/permission/f-range-permission.ts b/packages/sheets/src/facade/permission/f-range-permission.ts
index cbd387a709..93f45e5680 100644
--- a/packages/sheets/src/facade/permission/f-range-permission.ts
+++ b/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
diff --git a/packages/sheets/src/facade/permission/f-worksheet-permission.ts b/packages/sheets/src/facade/permission/f-worksheet-permission.ts
index 55a4303c92..743becdfc9 100644
--- a/packages/sheets/src/facade/permission/f-worksheet-permission.ts
+++ b/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
diff --git a/packages/sheets/src/facade/permission/util.ts b/packages/sheets/src/facade/permission/util.ts
index a2aec985cb..3b925e6f79 100644
--- a/packages/sheets/src/facade/permission/util.ts
+++ b/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,
diff --git a/packages/ui/src/facade/f-menu-builder.ts b/packages/ui/src/facade/f-menu-builder.ts
index 17cb6164af..670f58c027 100644
--- a/packages/ui/src/facade/f-menu-builder.ts
+++ b/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 } = {};