fix(modeling): fix command handler JSDocs

lib/features/modeling/cmd/AddLaneHandler.js

@@ -12,11 +12,19 @@ import {
   LANE_INDENTATION
 } from '../util/LaneUtil';
 
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('../Modeling').default} Modeling
+ * @typedef {import('../../space-tool/BpmnSpaceTool').default} SpaceTool
+ */
 
 /**
  * A handler that allows us to add a new lane
  * above or below an existing one.
  *
+ * @implements {CommandHandler}
+ *
  * @param {Modeling} modeling
  * @param {SpaceTool} spaceTool
  */

lib/features/modeling/cmd/IdClaimHandler.js

@@ -1,3 +1,14 @@
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('../../../model/Types').Moddle} Moddle
+ */
+
+/**
+ * @implements {CommandHandler}
+ *
+ * @param {Moddle} moddle
+ */
 export default function IdClaimHandler(moddle) {
   this._moddle = moddle;
 }

lib/features/modeling/cmd/ResizeLaneHandler.js

@@ -17,11 +17,24 @@ import {
   substractTRBL
 } from 'diagram-js/lib/features/resize/ResizeUtil';
 
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('../Modeling').default} Modeling
+ * @typedef {import('../../space-tool/BpmnSpaceTool').default} SpaceTool
+ *
+ * @typedef {import('../../../model/Types').BpmnShape} BpmnShape
+ *
+ * @typedef {import('diagram-js/lib/util/Types').Rect} Rect
+ */
 
 /**
  * A handler that resizes a lane.
  *
+ * @implements {CommandHandler}
+ *
  * @param {Modeling} modeling
+ * @param {SpaceTool} spaceTool
  */
 export default function ResizeLaneHandler(modeling, spaceTool) {
   this._modeling = modeling;
@@ -51,8 +64,8 @@ ResizeLaneHandler.prototype.preExecute = function(context) {
 /**
  * Resize balanced, adjusting next / previous lane sizes.
  *
- * @param {djs.model.Shape} shape
- * @param {Bounds} newBounds
+ * @param {BpmnShape} shape
+ * @param {Rect} newBounds
  */
 ResizeLaneHandler.prototype.resizeBalanced = function(shape, newBounds) {
 
@@ -73,8 +86,8 @@ ResizeLaneHandler.prototype.resizeBalanced = function(shape, newBounds) {
 /**
  * Resize, making actual space and moving below / above elements.
  *
- * @param {djs.model.Shape} shape
- * @param {Bounds} newBounds
+ * @param {BpmnShape} shape
+ * @param {Rect} newBounds
  */
 ResizeLaneHandler.prototype.resizeSpace = function(shape, newBounds) {
   var spaceTool = this._spaceTool;

lib/features/modeling/cmd/SetColorHandler.js

@@ -14,12 +14,24 @@ import {
   isLabel
 } from '../../../util/LabelUtil';
 
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('diagram-js/lib/command/CommandStack').default} CommandStack
+ *
+ * @typedef {import('../../../model/Types').ModdleElement} ModdleElement
+ */
+
 var DEFAULT_COLORS = {
   fill: undefined,
   stroke: undefined
 };
 
-
+/**
+ * @implements {CommandHandler}
+ *
+ * @param {CommandStack} commandStack
+ */
 export default function SetColorHandler(commandStack) {
   this._commandStack = commandStack;
 
@@ -102,22 +114,22 @@ SetColorHandler.prototype.postExecute = function(context) {
 };
 
 /**
- * Convert color from rgb(a)/hsl to hex. Returns `null` for unknown color names and for colors
- * with alpha less than 1.0. This depends on `<canvas>` serialization of the `context.fillStyle`.
+ * Convert color from rgb(a)/hsl to hex. Returns `null` for unknown color names
+ * and for colors with alpha less than 1.0. This depends on `<canvas>`
+ * serialization of the `context.fillStyle`.
  * Cf. https://html.spec.whatwg.org/multipage/canvas.html#dom-context-2d-fillstyle
  *
  * @example
- * ```js
- * var color = 'fuchsia';
- * console.log(colorToHex(color));
- * // "#ff00ff"
- * color = 'rgba(1,2,3,0.4)';
- * console.log(colorToHex(color));
- * // null
+ *
+ * ```javascript
+ * colorToHex('fuchsia'); // "#ff00ff"
+ *
+ * colorToHex('rgba(1, 2, 3, 0.4)'); // null
  * ```
  *
  * @param {string} color
- * @returns {string|null}
+ *
+ * @return {string|null}
  */
 function colorToHex(color) {
   var context = document.createElement('canvas').getContext('2d');
@@ -138,7 +150,8 @@ function isConnection(element) {
 
 /**
  * Add legacy properties if required.
- * @param {{ 'border-color': string?, 'background-color': string? }} di
+ *
+ * @param {ModdleElement} di
  */
 function ensureLegacySupport(di) {
   if ('border-color' in di) {

lib/features/modeling/cmd/SplitLaneHandler.js

@@ -3,12 +3,21 @@ import {
   LANE_INDENTATION
 } from '../util/LaneUtil';
 
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('../Modeling').default} Modeling
+ * @typedef {import('diagram-js/lib/i18n/translate/translate').default} Translate
+ */
 
 /**
  * A handler that splits a lane into a number of sub-lanes,
  * creating new sub lanes, if necessary.
  *
+ * @implements {CommandHandler}
+ *
  * @param {Modeling} modeling
+ * @param {Translate} translate
  */
 export default function SplitLaneHandler(modeling, translate) {
   this._modeling = modeling;

lib/features/modeling/cmd/UpdateCanvasRootHandler.js

@@ -5,7 +5,19 @@ import {
 
 import { getDi } from '../../../util/ModelUtil';
 
-
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('diagram-js/lib/core/Canvas').default} Canvas
+ * @typedef {import('../Modeling').default} Modeling
+ */
+
+/**
+ * @implements {CommandHandler}
+ *
+ * @param {Canvas} canvas
+ * @param {Modeling} modeling
+ */
 export default function UpdateCanvasRootHandler(canvas, modeling) {
   this._canvas = canvas;
   this._modeling = modeling;

lib/features/modeling/cmd/UpdateFlowNodeRefsHandler.js

@@ -16,12 +16,24 @@ import {
   asTRBL
 } from 'diagram-js/lib/layout/LayoutUtil';
 
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
+ *
+ * @typedef {import('../../../model/Types').BpmnShape} BpmnShape
+ */
+
 var FLOW_NODE_REFS_ATTR = 'flowNodeRef',
     LANES_ATTR = 'lanes';
 
 
 /**
- * A handler that updates lane refs on changed elements
+ * A handler that updates lane refs on changed elements.
+ *
+ * @implements {CommandHandler}
+ *
+ * @param {ElementRegistry} elementRegistry
  */
 export default function UpdateFlowNodeRefsHandler(elementRegistry) {
   this._elementRegistry = elementRegistry;
@@ -31,8 +43,17 @@ UpdateFlowNodeRefsHandler.$inject = [
   'elementRegistry'
 ];
 
-
-UpdateFlowNodeRefsHandler.prototype.computeUpdates = function(flowNodeShapes, laneShapes) {
+/**
+ * @param {BpmnShape} flowNodeShapes
+ * @param {BpmnShape} laneShapes
+ *
+ * @returns { {
+ *   flowNode: BpmnShape;
+ *   add: BpmnShape[];
+ *   remove: BpmnShape[];
+ * }[] }
+ */
+UpdateFlowNodeRefsHandler.prototype._computeUpdates = function(flowNodeShapes, laneShapes) {
 
   var handledNodes = [];
 
@@ -139,7 +160,7 @@ UpdateFlowNodeRefsHandler.prototype.execute = function(context) {
   var updates = context.updates;
 
   if (!updates) {
-    updates = context.updates = this.computeUpdates(context.flowNodeShapes, context.laneShapes);
+    updates = context.updates = this._computeUpdates(context.flowNodeShapes, context.laneShapes);
   }
 
 

lib/features/modeling/cmd/UpdateModdlePropertiesHandler.js

@@ -9,6 +9,20 @@ import {
   getBusinessObject
 } from '../../../util/ModelUtil';
 
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
+ *
+ * @typedef {import('../../../model/Types').BpmnShape} BpmnShape
+ * @typedef {import('../../../model/Types').ModdleElement} ModdleElement
+ */
+
+/**
+ * @implements {CommandHandler}
+ *
+ * @param {ElementRegistry} elementRegistry
+ */
 export default function UpdateModdlePropertiesHandler(elementRegistry) {
   this._elementRegistry = elementRegistry;
 }
@@ -28,7 +42,7 @@ UpdateModdlePropertiesHandler.prototype.execute = function(context) {
   // TODO(nikku): we need to ensure that ID properties
   // are properly registered / unregistered via
   // this._moddle.ids.assigned(id)
-  var changed = context.changed || this.getVisualReferences(moddleElement).concat(element);
+  var changed = context.changed || this._getVisualReferences(moddleElement).concat(element);
   var oldProperties = context.oldProperties || getModdleProperties(moddleElement, keys(properties));
 
   setModdleProperties(moddleElement, properties);
@@ -54,9 +68,9 @@ UpdateModdlePropertiesHandler.prototype.revert = function(context) {
  *
  * @param {ModdleElement} moddleElement
  *
- * @return {Array<djs.model.Element>}
+ * @return {BpmnShape[]}
  */
-UpdateModdlePropertiesHandler.prototype.getVisualReferences = function(moddleElement) {
+UpdateModdlePropertiesHandler.prototype._getVisualReferences = function(moddleElement) {
 
   var elementRegistry = this._elementRegistry;
 

lib/features/modeling/cmd/UpdatePropertiesHandler.js

@@ -10,6 +10,19 @@ import {
   getDi
 } from '../../../util/ModelUtil';
 
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ * @typedef {import('diagram-js/lib/command/CommandStack').CommandContext} CommandContext
+ *
+ * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
+ * @typedef {import('../../../model/Types').Moddle} Moddle
+ * @typedef {import('diagram-js/lib/i18n/translate/translate').default} Translate
+ * @typedef {import('../Modeling').default} Modeling
+ * @typedef {import('../../../draw/TextRenderer').default} TextRenderer
+ *
+ * @typedef {import('../../../model/Types').BpmnElement} BpmnElement
+ */
+
 var DEFAULT_FLOW = 'default',
     ID = 'id',
     DI = 'di';
@@ -27,6 +40,14 @@ var NULL_DIMENSIONS = {
  *
  * Use respective diagram-js provided handlers if you would
  * like to perform automated modeling.
+ *
+ * @implements {CommandHandler}
+ *
+ * @param {ElementRegistry} elementRegistry
+ * @param {Moddle} moddle
+ * @param {Translate} translate
+ * @param {Modeling} modeling
+ * @param {TextRenderer} textRenderer
  */
 export default function UpdatePropertiesHandler(
     elementRegistry, moddle, translate,
@@ -51,14 +72,14 @@ UpdatePropertiesHandler.$inject = [
 // api //////////////////////
 
 /**
- * Updates a BPMN element with a list of new properties
+ * Update a BPMN element's properties.
  *
- * @param {Object} context
- * @param {djs.model.Base} context.element the element to update
- * @param {Object} context.properties a list of properties to set on the element's
- *                                    businessObject (the BPMN model element)
+ * @param { {
+ *   element: BpmnElement;
+ *   properties: Record<string, any>;
+ * } & CommandContext } context
  *
- * @return {Array<djs.model.Base>} the updated element
+ * @return {BpmnElement[]}
  */
 UpdatePropertiesHandler.prototype.execute = function(context) {
 
@@ -127,11 +148,15 @@ UpdatePropertiesHandler.prototype.postExecute = function(context) {
 };
 
 /**
- * Reverts the update on a BPMN elements properties.
+ * Revert updating a BPMN element's properties.
  *
- * @param  {Object} context
+ * @param { {
+ *   element: BpmnElement;
+ *   properties: Record<string, any>;
+ *   oldProperties: Record<string, any>;
+ * } & CommandContext } context
  *
- * @return {djs.model.Base} the updated element
+ * @return {BpmnElement[]}
  */
 UpdatePropertiesHandler.prototype.revert = function(context) {
 
@@ -220,13 +245,12 @@ function setDiProperties(di, properties) {
 var referencePropertyNames = [ 'default' ];
 
 /**
- * Make sure we unwrap the actual business object
- * behind diagram element that may have been
- * passed as arguments.
+ * Make sure we unwrap the actual business object behind diagram element that
+ * may have been passed as arguments.
  *
- * @param  {Object} properties
+ * @param  {Record<string, any>} properties
  *
- * @return {Object} unwrappedProps
+ * @return {Record<string, any>} unwrappedProps
  */
 function unwrapBusinessObjects(properties) {
 

lib/features/modeling/cmd/UpdateSemanticParentHandler.js

@@ -1,3 +1,14 @@
+/**
+ * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+ *
+ * @typedef {import('../BpmnUpdater').default} BpmnUpdater
+ */
+
+/**
+ * @implements {CommandHandler}
+ *
+ * @param {BpmnUpdater} bpmnUpdater
+ */
 export default function UpdateSemanticParentHandler(bpmnUpdater) {
   this._bpmnUpdater = bpmnUpdater;
 }