From e234c19ca865797ed514e4a4bb737f2ffceb81b3 Mon Sep 17 00:00:00 2001 From: GogoVega <92022724+GogoVega@users.noreply.github.com> Date: Wed, 18 Dec 2024 15:10:21 +0100 Subject: [PATCH] Fix the jsdoc syntax and docs API methods --- .../@node-red/editor-client/src/js/history.js | 112 +++++++++++++++--- 1 file changed, 94 insertions(+), 18 deletions(-) diff --git a/packages/node_modules/@node-red/editor-client/src/js/history.js b/packages/node_modules/@node-red/editor-client/src/js/history.js index 3159a4919..02747892c 100644 --- a/packages/node_modules/@node-red/editor-client/src/js/history.js +++ b/packages/node_modules/@node-red/editor-client/src/js/history.js @@ -39,6 +39,7 @@ RED.history = (function () { * & (AddEvent | DeleteEvent | EditEvent | MoveEvent | MultiEvent | ReorderEvent | * ReplaceEvent | CreateSubflowEvent | DeleteSubflowEvent | AddToGroupEvent | * CreateGroupEvent | UngroupEvent | RemoveFromGroupEvent) } HistoryEvent + * @memberof RED.history */ /** @@ -76,11 +77,13 @@ RED.history = (function () { * @property {Array} [groups] An array with added groups * @property {Array} [junctions] An array with added junctions * @property {Array} [links] An array with added links - * @property {Array} [nodes] An array with added nodes + * @property {Array} [nodes] An array with added node ids * @property {Array} [removedLinks] An array with removed links - * @property {{ id: string; changed?: boolean; instances: Array; }} [subflow] + * @property {{ id: string, changed: boolean | undefined, + * instances: Array }} [subflow] * @property {Array} [subflows] An array with added subflows (tabs) * @property {Array} [workspaces] An array with added workspaces + * @memberof RED.history * * @param {AddEvent} ev The history event to undo * @param {object} [modifiedTabs] @@ -220,17 +223,22 @@ RED.history = (function () { * @typedef {object} DeleteEvent * @property {"delete"} t The history event type * @property {Record} [changes] An object with changes. - * The key is the id of a node and the value is an object with the changes to apply + * The key is the id of a node and the value is an object with the changes + * to apply * @property {Array} [createdLinks] An array with created links * @property {Array} [groups] An array with removed groups * @property {Array} [junctions] An array with removed junctions * @property {Array} [links] An array with removed links * @property {Array} [nodes] An array with removed nodes - * @property {{ id?: string; instances?: Array; status?: string;}} [subflow] - * @property {Array} [subflowInputs] An array with removed subflow input - * @property {Array} [subflowOutputs] An array with removed subflow outputs + * @property {{ id: string | undefined, instances: Array | undefined, + * status: string | undefined }} [subflow] + * @property {Array} [subflowInputs] An array with removed + * subflow input + * @property {Array} [subflowOutputs] An array with removed + * subflow outputs * @property {Array} [subflows] An array with removed subflows (tabs) * @property {Array} [workspaces] An array with removed workspace + * @memberof RED.history * * @param {DeleteEvent} ev The history event to undo * @param {object} [modifiedTabs] @@ -436,10 +444,12 @@ RED.history = (function () { * @property {"move"} t The history event type * @property {Group} [addToGroup] The group in which the nodes were added * @property {Array} [links] - * @property {Array<{ n: Node; ox: number; oy: number; dx: number; - * dy: number; }>} nodes An array with nodes moved + * @property {Array<{ n: Node, ox: number, oy: number, dx: number, + * dy: number }>} nodes An array with nodes moved * @property {Array} [removedLinks] - * @property {Group} [removeFromGroup] The group in which the nodes were removed + * @property {Group} [removeFromGroup] The group in which the nodes were + * removed + * @memberof RED.history * * @param {MoveEvent} ev The history event to undo * @returns {MoveEvent} The generated history event to redo @@ -506,8 +516,9 @@ RED.history = (function () { * @property {Array} [nodes] An array with subflow node ids * @property {Array} [removedLinks] An array with removed links * (during conversion to Subflow - links from active workspace) - * @property {{ subflow: Subflow; offsetX?: number; - * offsetY?: number; }} subflow The subflow created to delete + * @property {{ subflow: Subflow, offsetX: number | undefined, + * offsetY: number | undefined }} subflow The subflow created to delete + * @memberof RED.history * * @param {CreateSubflowEvent} ev The history event to undo * @returns {DeleteSubflowEvent} The generated history event to redo @@ -580,10 +591,11 @@ RED.history = (function () { * undo conversion to Subflow - links inside the subflow) * @property {Array} [movedNodes] An array with nodes to move to the * subflow to create - * @property {{ subflow: Subflow; offsetX?: number; - * offsetY?: number; }} subflow The deleted subflow to create + * @property {{ subflow: Subflow, offsetX: number | undefined, + * offsetY: number | undefined }} subflow The deleted subflow to create * @property {Array} [subflows] An array with subflow nodes * (redo conversion to subflow) + * @memberof RED.history * * @param {DeleteSubflowEvent} ev The history event to undo * @returns {CreateSubflowEvent} The generated history event to redo @@ -655,10 +667,11 @@ RED.history = (function () { * * @typedef {object} ReorderEvent * @property {"reorder"} t The history event type - * @property {{ from: string; to: string; z: string; }} [nodes] + * @property {{ from: string, to: string, z: string }} [nodes] * @property {object} [workspaces] * @property {Array} workspaces[].from Ordered array of workspace ids * @property {Array} workspaces[].to Ordered array of workspace ids + * @memberof RED.history * * @param {ReorderEvent} ev The history event to undo * @returns {ReorderEvent} The generated history event to redo @@ -696,6 +709,7 @@ RED.history = (function () { * @typedef {object} CreateGroupEvent * @property {"createGroup"} t The history event type * @property {Array} [groups] An array with groups to remove + * @memberof RED.history * * @param {CreateGroupEvent} ev The history event to undo * @returns {UngroupEvent} The generated history event to redo @@ -724,6 +738,7 @@ RED.history = (function () { * @typedef {object} UngroupEvent * @property {"ungroup"} t The history event type * @property {Array} [groups] An array with groups to create + * @memberof RED.history * * @param {UngroupEvent} ev The history event to undo * @returns {CreateGroupEvent} The generated history event to redo @@ -766,6 +781,7 @@ RED.history = (function () { * @property {Array | Node} [nodes] An array of nodes or one node * to remove from the group * @property {boolean} [reparent] Either to re-add to parent group + * @memberof RED.history * * @param {AddToGroupEvent} ev The history event to undo * @returns {RemoveFromGroupEvent} The generated history event to redo @@ -796,6 +812,7 @@ RED.history = (function () { * @property {Array | Node} [nodes] An array of nodes or one node * to add to the group * @property {boolean} [reparent] Either to re-add to parent group + * @memberof RED.history * * @param {RemoveFromGroupEvent} ev The history event to undo * @returns {AddToGroupEvent} The generated history event to redo @@ -828,8 +845,10 @@ RED.history = (function () { * @property {Array} [links] An array with removed links * @property {Node} node The current node/subflow * @property {object} [outputMap] - * @property {{ instances?: Array; inputCount?: number; - * outputCount?: number; status?: string; }} [subflow] Subflow properties + * @property {{ instances: Array | undefined, + * inputCount: number | undefined, outputCount: number | undefined, + * status: string | undefined }} [subflow] Subflow properties + * @memberof RED.history * * @param {EditEvent} ev The history event to undo * @returns {EditEvent} The generated history event to redo @@ -1019,15 +1038,18 @@ RED.history = (function () { * @property {Record} moved An object with a node id * as key and the node moved property as value * @property {string} rev A revision version - * + * @memberof RED.history + * * @typedef {object} IncompleteReplaceEvent * @property {"replace"} t The history event type * @property {false} [complete] Either the {@link ReplaceEvent.config} * property contains the complete flows * @property {Array} config An array with config nodes and/or * subflow definitions to replace. + * @memberof RED.history * * @typedef {CompleteReplaceEvent|IncompleteReplaceEvent} ReplaceEvent + * @memberof RED.history * * @param {ReplaceEvent} ev The history event to undo * @returns {ReplaceEvent} The generated history event to redo @@ -1111,6 +1133,7 @@ RED.history = (function () { * @typedef {object} MultiEvent * @property {"multi"} t The history event type * @property {Array} events An array with events + * @memberof RED.history * * @param {MultiEvent} ev The history event to undo * @returns {MultiEvent} The generated history event to redo @@ -1131,7 +1154,7 @@ RED.history = (function () { } /** - * Called to undo the history event + * Called to undo/redo the history event * * @param {HistoryEvent} ev The history event to undo * @returns {HistoryEvent} The generated history event to redo @@ -1200,21 +1223,50 @@ RED.history = (function () { undoHistory[i].dirty = true; } }, + /** + * Returns a list with undo events. + * @returns {Array} The list with undo events + * @memberof RED.history + */ list: function () { return undoHistory; }, + /** + * Returns a list with redo events. + * @returns {Array} The list with redo events + * @memberof RED.history + */ listRedo: function () { return redoHistory; }, + /** + * Returns the size of the list with redo events. + * @returns {number} The size of the redo list + * @memberof RED.history + */ depth: function () { return undoHistory.length; }, + /** + * Pushes an event to the History. This event can be undo by + * calling {@link RED.history.pop pop}. + * @param {HistoryEvent} ev The event to push + * @returns {void} + * @memberof RED.history + */ push: function (ev) { undoHistory.push(ev); redoHistory = []; RED.menu.setDisabled("menu-item-edit-undo", false); RED.menu.setDisabled("menu-item-edit-redo", true); }, + /** + * Called to undo an event. + * Takes the last event of the undo list, do undo event and adds + * the redo event generated to the redo list. + * @returns {void} + * @memberof RED.history + */ pop: function () { const ev = undoHistory.pop(); const rev = undoEvent(ev); @@ -1226,9 +1278,21 @@ RED.history = (function () { RED.menu.setDisabled("menu-item-edit-undo", undoHistory.length === 0); RED.menu.setDisabled("menu-item-edit-redo", redoHistory.length === 0); }, + /** + * Returns the last event of undo list. + * @returns {HistoryEvent} + * @memberof RED.history + */ peek: function () { return undoHistory[undoHistory.length - 1]; }, + /** + * Replaces the last event of undo list by the event given + * in parameter. + * @param {HistoryEvent} ev The event to replace + * @returns {void} + * @memberof RED.history + */ replace: function (ev) { if (undoHistory.length === 0) { RED.history.push(ev); @@ -1236,12 +1300,24 @@ RED.history = (function () { undoHistory[undoHistory.length - 1] = ev; } }, + /** + * Clears the undo list and redo list. + * @returns {void} + * @memberof RED.history + */ clear: function () { undoHistory = []; redoHistory = []; RED.menu.setDisabled("menu-item-edit-undo", true); RED.menu.setDisabled("menu-item-edit-redo", true); }, + /** + * Called to redo an event. + * Takes the last event of the redo list, do redo event and adds + * the undo event generated to the undo list. + * @returns {void} + * @memberof RED.history + */ redo: function () { const ev = redoHistory.pop();