From 0206ff540a1f3669671a9d2ab4d1c89e81d0964a Mon Sep 17 00:00:00 2001
From: Sidharth Vinod <sidharthv96@gmail.com>
Date: Fri, 24 Feb 2023 12:20:31 +0530
Subject: [PATCH] fix(#4140): Deprecate mermaidAPI.render

---
 docs/config/setup/modules/mermaidAPI.md |  2 +-
 packages/mermaid/src/mermaid.ts         | 26 +++++++++++++++++++++++++
 packages/mermaid/src/mermaidAPI.ts      | 25 ++----------------------
 3 files changed, 29 insertions(+), 24 deletions(-)

diff --git a/docs/config/setup/modules/mermaidAPI.md b/docs/config/setup/modules/mermaidAPI.md
index 0406baa81a..8b24a89172 100644
--- a/docs/config/setup/modules/mermaidAPI.md
+++ b/docs/config/setup/modules/mermaidAPI.md
@@ -95,7 +95,7 @@ mermaid.initialize(config);
 
 #### Defined in
 
-[mermaidAPI.ts:680](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L680)
+[mermaidAPI.ts:659](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L659)
 
 ## Functions
 
diff --git a/packages/mermaid/src/mermaid.ts b/packages/mermaid/src/mermaid.ts
index 49e849148b..db72aeedba 100644
--- a/packages/mermaid/src/mermaid.ts
+++ b/packages/mermaid/src/mermaid.ts
@@ -337,6 +337,32 @@ const parse = async (text: string, parseOptions?: ParseOptions): Promise<boolean
   });
 };
 
+/**
+ * Function that renders an svg with a graph from a chart definition. Usage example below.
+ *
+ * ```javascript
+ * mermaid.initialize({
+ *   startOnLoad: true,
+ * });
+ * $(function () {
+ *   const graphDefinition = 'graph TB\na-->b';
+ *   const cb = function (svgGraph) {
+ *     console.log(svgGraph);
+ *   };
+ *   mermaid.render('id1', graphDefinition, cb);
+ * });
+ * ```
+ *
+ * @param id - The id for the SVG element (the element to be rendered)
+ * @param text - The text for the graph definition
+ * @param cb - Callback which is called after rendering is finished with the svg code as in param.
+ * @param svgContainingElement - HTML element where the svg will be inserted. (Is usually element with the .mermaid class)
+ *   If no svgContainingElement is provided then the SVG element will be appended to the body.
+ *    Selector to element in which a div with the graph temporarily will be
+ *   inserted. If one is provided a hidden div will be inserted in the body of the page instead. The
+ *   element will be removed when rendering is completed.
+ * @returns Returns the rendered element as a string containing the SVG definition.
+ */
 const render = (id: string, text: string, container?: Element): Promise<RenderResult> => {
   return new Promise((resolve, reject) => {
     // This promise will resolve when the mermaidAPI.render call is done.
diff --git a/packages/mermaid/src/mermaidAPI.ts b/packages/mermaid/src/mermaidAPI.ts
index 64e0bbce2e..66bc99e5e3 100644
--- a/packages/mermaid/src/mermaidAPI.ts
+++ b/packages/mermaid/src/mermaidAPI.ts
@@ -370,30 +370,9 @@ export const removeExistingElements = (
 };
 
 /**
- * Function that renders an svg with a graph from a chart definition. Usage example below.
+ * @deprecated - use the `mermaid.render` function instead of `mermaid.mermaidAPI.render`
  *
- * ```javascript
- * mermaidAPI.initialize({
- *   startOnLoad: true,
- * });
- * $(function () {
- *   const graphDefinition = 'graph TB\na-->b';
- *   const cb = function (svgGraph) {
- *     console.log(svgGraph);
- *   };
- *   mermaidAPI.render('id1', graphDefinition, cb);
- * });
- * ```
- *
- * @param id - The id for the SVG element (the element to be rendered)
- * @param text - The text for the graph definition
- * @param cb - Callback which is called after rendering is finished with the svg code as in param.
- * @param svgContainingElement - HTML element where the svg will be inserted. (Is usually element with the .mermaid class)
- *   If no svgContainingElement is provided then the SVG element will be appended to the body.
- *    Selector to element in which a div with the graph temporarily will be
- *   inserted. If one is provided a hidden div will be inserted in the body of the page instead. The
- *   element will be removed when rendering is completed.
- * @returns Returns the rendered element as a string containing the SVG definition.
+ * Deprecated for external use.
  */
 
 const render = async function (