Fix the jsdoc syntax and docs API methods

This commit is contained in:
GogoVega 2024-12-18 15:10:21 +01:00
parent 4aff2ae08a
commit e234c19ca8
No known key found for this signature in database
GPG Key ID: E1E048B63AC5AC2B

View File

@ -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<Group>} [groups] An array with added groups
* @property {Array<Junction>} [junctions] An array with added junctions
* @property {Array<Link>} [links] An array with added links
* @property {Array<Node>} [nodes] An array with added nodes
* @property {Array<string>} [nodes] An array with added node ids
* @property {Array<Link>} [removedLinks] An array with removed links
* @property {{ id: string; changed?: boolean; instances: Array<Node>; }} [subflow]
* @property {{ id: string, changed: boolean | undefined,
* instances: Array<Node> }} [subflow]
* @property {Array<Subflow>} [subflows] An array with added subflows (tabs)
* @property {Array<Workspace>} [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<string, object>} [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<Link>} [createdLinks] An array with created links
* @property {Array<Group>} [groups] An array with removed groups
* @property {Array<Junction>} [junctions] An array with removed junctions
* @property {Array<Link>} [links] An array with removed links
* @property {Array<Node>} [nodes] An array with removed nodes
* @property {{ id?: string; instances?: Array<Node>; status?: string;}} [subflow]
* @property {Array<SubflowNode>} [subflowInputs] An array with removed subflow input
* @property {Array<SubflowNode>} [subflowOutputs] An array with removed subflow outputs
* @property {{ id: string | undefined, instances: Array<Node> | undefined,
* status: string | undefined }} [subflow]
* @property {Array<SubflowNode>} [subflowInputs] An array with removed
* subflow input
* @property {Array<SubflowNode>} [subflowOutputs] An array with removed
* subflow outputs
* @property {Array<Subflow>} [subflows] An array with removed subflows (tabs)
* @property {Array<Workspace>} [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<Link>} [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<Link>} [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<string>} [nodes] An array with subflow node ids
* @property {Array<Link>} [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<Node>} [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<Subflow>} [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<string>} workspaces[].from Ordered array of workspace ids
* @property {Array<string>} 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<Group>} [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<Group>} [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> | 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> | 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<Link>} [links] An array with removed links
* @property {Node} node The current node/subflow
* @property {object} [outputMap]
* @property {{ instances?: Array<Node>; inputCount?: number;
* outputCount?: number; status?: string; }} [subflow] Subflow properties
* @property {{ instances: Array<Node> | 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<string, boolean>} 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<Node>} 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<HistoryEvent>} 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<HistoryEvent>} The list with undo events
* @memberof RED.history
*/
list: function () {
return undoHistory;
},
/**
* Returns a list with redo events.
* @returns {Array<HistoryEvent>} 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();