The methods insertVertex and insertEdge come from mxGraph. They take a long list of parameters, which makes them hard to use and maintain. It's also not practical when adding new features, since each new feature often requires an additional parameter.

• insertVertex legacy signature:
  

  maxGraph/packages/core/src/view/mixins/VertexMixin.type.ts

  Lines 86 to 97 in 9130103

  	insertVertex(
  	parent: Cell | null,
  	id: string | null | undefined,
  	value: any,
  	x?: number,
  	y?: number,
  	width?: number,
  	height?: number,
  	style?: CellStyle,
  	relative?: boolean,
  	geometryClass?: typeof Geometry
  	): Cell;

• insertEdge legacy signature:
  

  maxGraph/packages/core/src/view/mixins/EdgeMixin.type.ts

  Lines 185 to 192 in 9130103

  	insertEdge(
  	parent: Cell | null,
  	id: string | null | undefined,
  	value: EdgeParametersValue,
  	source?: Cell | null,
  	target?: Cell | null,
  	style?: CellStyle
  	): Cell;

In maxGraph, we've already introduced new methods that take a single options object instead of a long list of arguments:

• New insertVertex method:
  

  maxGraph/packages/core/src/view/mixins/VertexMixin.type.ts

  Line 132 in 9130103

  insertVertex(params: VertexParameters): Cell;

• New insertEdge method:
  

  maxGraph/packages/core/src/view/mixins/EdgeMixin.type.ts

  Line 201 in 9130103

  insertEdge(params: EdgeParameters): Cell;

These new APIs are easier to use:

• Optional parameters can just be omitted (no need for null or undefined)
• They are easier to read
• Easier to extend with new features

However, many examples and parts of the documentation still use the old methods. That makes it harder to encourage adoption of the new APIs and to plan the removal of the legacy ones.

Proposal

We should officially deprecate the legacy methods and promote the new ones. We won’t remove them yet, to avoid breaking changes and help users migrating from mxGraph.

Tasks (non-exhaustive)

• Mark insertVertex and insertEdge as @deprecated in the source code
  • Include the version in which they are deprecated
• Update JSDoc examples to use the new API. Done in refactor: remove reference to legacy insert cells methods #876
• Update documentation references. Done in refactor: remove reference to legacy insert cells methods #876
  • lots of usage in tutorial/manual
  • in particular in https://maxgraph.github.io/maxGraph/docs/manual/model-and-transactions#inserting-cells
• Update stories and examples:
  • examples in this repository. Done in refactor: remove reference to legacy insert cells methods #876
  • examples in https://github.com/maxGraph/maxGraph-integration-examples/
  • stories