chore: add comments

packages/drawing-ui/src/controllers/image-cropper.controller.ts

@@ -269,7 +269,7 @@ export class ImageCropperController extends Disposable {
     }
 
     private _searchCropObject(scene: Scene) {
-        const objects = scene.getAllObjects();
+        const objects = scene.getAllObjectsByOrder();
 
         for (const object of objects) {
             if (object instanceof ImageCropperObject) {

packages/engine-render/src/group.ts

@@ -156,19 +156,13 @@ export class Group extends BaseObject {
             }
 
             object.parent = this;
-
             object.isInGroup = true;
-
             object.groupKey = this.oKey;
-
             this._objects.push(object);
         } else {
             o.parent = this;
-
             o.isInGroup = true;
-
             o.groupKey = this.oKey;
-
             this._objects.push(o);
         }
     }

packages/engine-render/src/layer.ts

@@ -61,21 +61,21 @@ export class Layer extends Disposable {
         this._initialCacheCanvas();
     }
 
-    disableCache() {
+    disableCache(): void {
         this._allowCache = false;
         this._cacheCanvas?.dispose();
         this._cacheCanvas = null;
     }
 
-    isAllowCache() {
+    isAllowCache(): boolean {
         return this._allowCache;
     }
 
     /**
-     * get objects which is visible and not in a group.
-     * @returns BaseObject[]
+     * Get direct visible children in order. (direct means object is not in group), default order is ascending by z-index.
+     * @returns {BaseObject[]} objects
      */
-    getObjectsByOrder() {
+    getObjectsByOrder(): BaseObject[] {
         const objects: BaseObject[] = [];
         this._objects.sort(sortRules);
         for (const o of this._objects) {
@@ -86,7 +86,11 @@ export class Layer extends Disposable {
         return objects;
     }
 
-    getObjectsByOrderForPick() {
+    /**
+     * Get visible and evented objects.
+     * @returns {BaseObject[]} objects
+     */
+    getObjectsByOrderForPick(): BaseObject[] {
         const objects: BaseObject[] = [];
         this._objects.sort(sortRules);
         for (const o of this._objects) {
@@ -98,17 +102,16 @@ export class Layer extends Disposable {
         return objects;
     }
 
-    getObjects() {
+    getObjects(): BaseObject[] {
         return this._objects;
     }
 
     /**
-     * insert o to _objects[]
-     * if o is a group, insert all its children and group itself to _objects[]
+     * Insert object to this._objects, if object is a group, insert all its children and group itself to _objects[]
      * @param o
-     * @returns this
+     * @returns {Layer} this
      */
-    addObject(o: BaseObject) {
+    addObject(o: BaseObject): Layer {
         if (o.classType === RENDER_CLASS_TYPE.GROUP) {
             const objects = (o as BaseObject).getObjects();
             for (const object of objects) {
@@ -151,7 +154,12 @@ export class Layer extends Disposable {
         }
     }
 
-    addObjects(objects: BaseObject[]) {
+    /**
+     * Insert objects to this._objects, if object is a group, insert all its children and group itself to _objects[]
+     * @param objects
+     * @returns {Layer} this
+     */
+    addObjects(objects: BaseObject[]): Layer {
         objects.forEach((o: BaseObject) => {
             this.addObject(o);
         });

packages/engine-render/src/scene.ts

@@ -343,11 +343,11 @@ export class Scene extends ThinScene {
         return null;
     }
 
-    getLayers() {
+    getLayers(): Layer[] {
         return this._layers;
     }
 
-    getLayer(zIndex: number = 1) {
+    getLayer(zIndex: number = 1): Layer {
         for (const layer of this._layers) {
             if (layer.zIndex === zIndex) {
                 return layer;
@@ -367,33 +367,42 @@ export class Scene extends ThinScene {
         return maxIndex;
     }
 
-    addLayer(...argument: Layer[]) {
+    addLayer(...argument: Layer[]): void {
         this._layers.push(...argument);
     }
 
-    override addObjects(objects: BaseObject[], zIndex: number = 1) {
+    /**
+     * Add objects to Layer( Layer is specfied by zIndex)
+     * If object is a group, insert all its children and group itself to _objects[].
+     * @param objects
+     * @param zIndex
+     * @returns {Scene} this
+     */
+    override addObjects(objects: BaseObject[], zIndex: number = 1): Scene {
         this.getLayer(zIndex)?.addObjects(objects);
         this._addObject$.next(this);
         return this;
     }
 
     /**
      * Add object to Layer (Layer is specified by zIndex).
+     * If object is a group, insert all its children and group itself to _objects[].
      * @param o
      * @param zIndex layer index
-     * @returns scene
+     * @returns {Scene} scene
      */
-    override addObject(o: BaseObject, zIndex: number = 1) {
+    override addObject(o: BaseObject, zIndex: number = 1): Scene {
         this.getLayer(zIndex)?.addObject(o);
         this._addObject$.next(this);
         return this;
     }
 
     /**
-     * make object parent to scene
+     * Set Scene as object parent, if object has no parent.
      * @param o
+     * @returns {void}
      */
-    override setObjectBehavior(o: BaseObject) {
+    override setObjectBehavior(o: BaseObject): void {
         if (!o.parent) {
             o.parent = this;
         }
@@ -403,7 +412,8 @@ export class Scene extends ThinScene {
         o.onIsAddedToParent$.emitEvent(this);
     }
 
-    removeObject(object?: BaseObject | string) {
+    // Why? return values is so strange! removeObject should return true/false, or didn't return anything.
+    removeObject(object?: BaseObject | string): Nullable<Scene> {
         if (object == null) {
             return;
         }
@@ -414,7 +424,7 @@ export class Scene extends ThinScene {
         return this;
     }
 
-    removeObjects(objects?: BaseObject[] | string[]) {
+    removeObjects(objects?: BaseObject[] | string[]): Nullable<Scene> {
         if (objects == null) {
             return;
         }
@@ -439,7 +449,7 @@ export class Scene extends ThinScene {
     //     return this;
     // }
 
-    getObjectsByLayer(zIndex: number) {
+    getObjectsByLayer(zIndex: number): BaseObject[] {
         const objects: BaseObject[] = [];
         this._layers.sort(sortRules);
         for (const layer of this._layers) {
@@ -451,10 +461,23 @@ export class Scene extends ThinScene {
     }
 
     /**
-     * get objects which is visible and not in a group in each layer.
+     * Get all objects of each Layer.
+     * @returns {BaseObject[]} objects
+     */
+    getAllObjects(): BaseObject[] {
+        const objects: BaseObject[] = [];
+        this._layers.sort(sortRules);
+        for (const layer of this._layers) {
+            objects.push(...layer.getObjects());
+        }
+        return objects;
+    }
+
+    /**
+     * Get objects which is visible and not in a group in each layer.
      * @returns BaseObject[]
      */
-    getAllObjects() {
+    getAllObjectsByOrder(): BaseObject[] {
         const objects: BaseObject[] = [];
         this._layers.sort(sortRules);
         for (const layer of this._layers) {
@@ -468,7 +491,7 @@ export class Scene extends ThinScene {
      * @param isDesc
      * @returns BaseObject[]
      */
-    getAllObjectsByOrder(isDesc: boolean = false) {
+    getAllObjectsByDescOrder(isDesc: boolean = false): BaseObject[] {
         const objects: BaseObject[] = [];
         const useSortRules = isDesc ? sortRulesByDesc : sortRules;
         this._layers.sort(useSortRules);
@@ -478,7 +501,12 @@ export class Scene extends ThinScene {
         return objects;
     }
 
-    getAllObjectsByOrderForPick(isDesc: boolean = false) {
+    /**
+     * Get visible and evented objects.
+     * @param isDesc
+     * @returns {BaseObject[]} objects
+     */
+    getAllObjectsByOrderForPick(isDesc: boolean = false): BaseObject[] {
         const objects: BaseObject[] = [];
         const useSortRules = isDesc ? sortRulesByDesc : sortRules;
         this._layers.sort(useSortRules);
@@ -488,7 +516,7 @@ export class Scene extends ThinScene {
         return objects;
     }
 
-    override getObject(oKey: string) {
+    override getObject(oKey: string): Nullable<BaseObject> {
         for (const layer of this._layers) {
             const objects = layer.getObjectsByOrder();
             for (const object of objects) {
@@ -499,7 +527,7 @@ export class Scene extends ThinScene {
         }
     }
 
-    getObjectIncludeInGroup(oKey: string) {
+    getObjectIncludeInGroup(oKey: string): Nullable<BaseObject> {
         for (const layer of this._layers) {
             const objects = layer.getObjects();
             for (const object of objects) {

packages/engine-render/src/shape/shape.ts

@@ -345,14 +345,14 @@ export abstract class Shape<T extends IShapeProps> extends BaseObject {
      * this[_key] = props[key]
      * @param props
      */
-    setProps(props?: T): void {
+    setProps(props?: T): Shape<T> {
         if (!props) {
-            return;
+            return this;
         }
 
         const themeKeys = Object.keys(props);
         if (themeKeys.length === 0) {
-            return;
+            return this;
         }
         themeKeys.forEach((key) => {
             if ((props as IKeyValue)[key] === undefined) {

packages/engine-render/src/viewport.ts

@@ -757,7 +757,7 @@ export class Viewport {
      * @param objects
      * @param isMaxLayer
      */
-    render(parentCtx?: UniverRenderingContext, objects: BaseObject[] = [], isMaxLayer = false) {
+    render(parentCtx?: UniverRenderingContext, objects: BaseObject[] = [], isMaxLayer = false): void {
         if (!this.shouldIntoRender()) {
             return;
         }

packages/sheets-drawing-ui/src/controllers/drawing-popup-menu.controller.ts

@@ -72,7 +72,7 @@ export class DrawingPopupMenuController extends RxDisposable {
     }
 
     private _hasCropObject(scene: Scene) {
-        const objects = scene.getAllObjects();
+        const objects = scene.getAllObjectsByOrder();
 
         for (const object of objects) {
             if (object instanceof ImageCropperObject) {

packages/sheets-drawing-ui/src/controllers/sheet-drawing-permission.controller.ts

@@ -66,7 +66,7 @@ export class SheetDrawingPermissionController extends Disposable {
                         if (scene == null) {
                             return;
                         }
-                        const objects = scene.getAllObjects();
+                        const objects = scene.getAllObjectsByOrder();
                         objects.forEach((object) => {
                             if (object.classType === RENDER_CLASS_TYPE.IMAGE && drawingDataValues.some((item) => object.oKey.includes(item.drawingId))) {
                                 scene.removeObject(object);
@@ -107,7 +107,7 @@ export class SheetDrawingPermissionController extends Disposable {
                         if (scene == null) {
                             return;
                         }
-                        const objects = scene.getAllObjects();
+                        const objects = scene.getAllObjectsByOrder();
                         objects.forEach((object) => {
                             if (object.classType === RENDER_CLASS_TYPE.IMAGE && drawingDataValues.some((item) => object.oKey.includes(item.drawingId))) {
                                 scene.detachTransformerFrom(object);
@@ -147,7 +147,7 @@ export class SheetDrawingPermissionController extends Disposable {
                         next: (permission) => {
                             initialViewPermission = permission;
                             this._drawingManagerService.setDrawingVisible(permission);
-                            const objects = scene.getAllObjects();
+                            const objects = scene.getAllObjectsByOrder();
                             const drawingData = this._drawingManagerService.getDrawingData(unitId, subUnitId);
                             const drawingDataValues = Object.values(drawingData);
                             if (permission) {
@@ -207,7 +207,7 @@ export class SheetDrawingPermissionController extends Disposable {
                         next: (permission) => {
                             initialEditPermission = permission;
                             this._drawingManagerService.setDrawingEditable(permission);
-                            const objects = scene.getAllObjects();
+                            const objects = scene.getAllObjectsByOrder();
                             const drawingData = this._drawingManagerService.getDrawingData(unitId, subUnitId);
                             const drawingDataValues = Object.values(drawingData);
                             if (permission) {
@@ -244,7 +244,7 @@ export class SheetDrawingPermissionController extends Disposable {
                                 return;
                             }
                             this._drawingManagerService.setDrawingEditable(true);
-                            const objects = scene.getAllObjects();
+                            const objects = scene.getAllObjectsByOrder();
                             objects.forEach((object) => {
                                 if (object.classType === RENDER_CLASS_TYPE.IMAGE && drawingDataValues.some((item) => object.oKey.includes(item.drawingId))) {
                                     scene.detachTransformerFrom(object);

packages/sheets-formula/src/controllers/formula-editor-show.controller.ts

@@ -38,8 +38,8 @@ import {
     IEditorBridgeService,
     ISheetSelectionRenderService,
     SelectionShape,
-    SheetSkeletonManagerService,
-} from '@univerjs/sheets-ui';
+    SelectionShape_DEPTH,
+    SheetSkeletonManagerService } from '@univerjs/sheets-ui';
 
 const REFRESH_ARRAY_SHAPE_MUTATIONS = [
     SetWorksheetRowHeightMutation.id,
@@ -257,7 +257,7 @@ export class FormulaEditorShowController extends Disposable implements IRenderMo
         const skeleton = this._sheetSkeletonManagerService.getCurrentSkeleton();
         if (!scene || !skeleton) return;
         const { rowHeaderWidth, columnHeaderHeight } = skeleton;
-        const control = new SelectionShape(scene, 100, false, this._themeService);
+        const control = new SelectionShape(scene, SelectionShape_DEPTH.FORMULA_EDITOR_SHOW, this._themeService, false);
         control.update(rangeWithCoord, rowHeaderWidth, columnHeaderHeight, style, primaryWithCoord);
         control.setEvent(false);
         this._previousShape = control;