Script to automatically generate Markdown API docs from source code.

package.json

@@ -76,7 +76,7 @@
         "serveWithWebCache": "npm run _releaseWebCache && npm run _serveWithWebCacheHelp && http-server ./dist -p 8000 -c-1",
         "serveExternal": "http-server . -p 8000 -a 0.0.0.0 --log-ip true -c-1",
         "createJSDocs": "gulp createJSDocs && git add docs",
-        "createMDXDocs": "node build/api-docs-generator.js",
+        "createMDDocs": "node build/api-docs-generator.js",
         "_translateStrings": "gulp translateStrings",
         "_minify": "r.js -o require.min.config.js && echo this is untested see https://stackoverflow.com/questions/14337970/minifying-requirejs-javascript-codebase-to-a-single-file"
     },

src/features/QuickViewManager.js

@@ -262,19 +262,17 @@ define(function (require, exports, module) {
      * 3. If non-null, but visible==false, we're waiting for HOVER_DELAY, which
      *    is tracked by hoverTimer. The state changes to visible==true as soon as
      *    there is a provider. If the mouse moves before then, timer is restarted.
-     *
-     * @type {{
-     *      visible: boolean,
-     *      editor: !Editor,
-     *      hoverTimer: number,             - setTimeout() token
-     *      start: !{line, ch},             - start of matched text range
-     *      end: !{line, ch},               - end of matched text range
-     *      content: !string,               - HTML content to display in popover
-     *      xpos: number,                   - x of center of popover
-     *      ytop: number,                   - y of top of matched text (when popover placed above text, normally)
-     *      ybot: number,                   - y of bottom of matched text (when popover moved below text, avoiding window top)
-     *      marker: ?CodeMirror.TextMarker  - only set once visible==true
-     * }}
+     * @typedef {Object} PopoverState
+     * @property {boolean} visible - Whether the popover is visible.
+     * @property {!Editor} editor - The editor instance associated with the popover.
+     * @property {number} hoverTimer - The token returned by setTimeout().
+     * @property {!{line: number, ch: number}} start - Start of the matched text range.
+     * @property {!{line: number, ch: number}} end - End of the matched text range.
+     * @property {!string} content - HTML content to display in the popover.
+     * @property {number} xpos - X-coordinate of the center of the popover.
+     * @property {number} ytop - Y-coordinate of the top of the matched text when popover is above the text.
+     * @property {number} ybot - Y-coordinate of the bottom of the matched text when popover is below the text.
+     * @property {?CodeMirror.TextMarker} marker - The text marker; only set once `visible` is `true`.
      * @private
      */
     let popoverState = null;
@@ -413,7 +411,7 @@ define(function (require, exports, module) {
      * Returns a popover array with the list of popovers to be rendered after filtering from providers.
      * @param results
      * @param providerInfos
-     * @return {*[]}
+     * @return {Object[]}
      * @private
      */
     function _getPopover(results, providerInfos) {

src/features/SelectionViewManager.js

@@ -218,17 +218,15 @@ define(function (require, exports, module) {
      * 3. If non-null, but visible==false, we're waiting for HOVER_DELAY, which
      *    is tracked by hoverTimer. The state changes to visible==true as soon as
      *    there is a provider. If the mouse moves before then, timer is restarted.
-     *
-     * @type {{
-     *      visible: boolean,
-     *      editor: !Editor,
-     *      start: !{line, ch},             - start of matched text range
-     *      end: !{line, ch},               - end of matched text range
-     *      content: !string,               - HTML content to display in popover
-     *      xpos: number,                   - x of center of popover
-     *      ytop: number,                   - y of top of matched text (when popover placed above text, normally)
-     *      ybot: number,                   - y of bottom of matched text (when popover moved below text, avoiding window top)
-     * }}
+     * @typedef {Object} PopoverState
+     * @property {boolean} visible - Whether the popover is visible.
+     * @property {!Editor} editor - The editor instance associated with the popover.
+     * @property {!{line: number, ch: number}} start - Start of the matched text range.
+     * @property {!{line: number, ch: number}} end - End of the matched text range.
+     * @property {!string} content - HTML content to display in the popover.
+     * @property {number} xpos - X-coordinate of the center of the popover.
+     * @property {number} ytop - Y-coordinate of the top of the matched text when the popover is placed above the text.
+     * @property {number} ybot - Y-coordinate of the bottom of the matched text when the popover is moved below the text.
      * @private
      */
     let popoverState = null;

src/utils/EventManager.js

@@ -143,17 +143,21 @@ define(function (require, exports, module) {
      * // to prevent collisions. EventHandlers starting with `ph-` and `br-` are reserved as system handlers
      * // and not available for use in extensions.
      * window.Phoenix.TRUSTED_ORIGINS ["http://mydomain.com"] = true;
+     * ```js
      * EventManager.registerEventHandler("`extensionName`-iframeMessageHandler", exports);
      * exports.on("iframeHelloEvent", function(_ev, event){
      *    console.log(event.data.message);
      * });
+     * ```
      *
      * // Now from your iframe, send a message to the above event handler using:
+     * ```js
      * window.parent.postMessage({
      *     handlerName: "`extensionName`-iframeMessageHandler",
      *     eventName: "iframeHelloEvent",
      *     message: "hello world"
      * }, '*');
+     * ```
      * // `you should replace * with the trusted domains list in production for security.` See how this can be
      * // done securely with this example: https://github.com/phcode-dev/phcode.live/blob/6d64386fbb9d671cdb64622bc48ffe5f71959bff/docs/virtual-server-loader.js#L43
      * // Abstract is that, pass in the parentOrigin as a query string parameter in iframe, and validate it against

src/utils/ExtensionInterface.js

@@ -48,11 +48,9 @@
  * ```js
  * let angularCli;
  * ExtensionInterface.waitAndGetExtensionInterface("angularCli").then(interfaceObj=> angularCli = interfaceObj);
- * ...
  * if(angularCli){ // check if angular cli is avilable
  * angularCli.callSomeFunction();
  * }
- * ...
  * ```
  *
  * **Note** that the `angularCli` interface is async populated as and when the cli extension is loaded and the
@@ -105,13 +103,13 @@ define(function (require, exports, module) {
      * getter to get hold of extensions interface predictably.
      *
      * To get a registered interface `angularCli`
+     * ```js
      * let angularCli;
      * ExtensionInterface.waitAndGetExtensionInterface("angularCli").then(interfaceObj=> angularCli = interfaceObj);
-     * ...
      * if(angularCli){ // check if angular cli is avilable
      * angularCli.callSomeFunction();
      * }
-     * ...
+     * ```
      *
      * @param extensionInterfaceName
      * @return {Promise}

src/utils/FeatureGate.js

@@ -89,7 +89,7 @@ define(function (require, exports, module) {
 
     /**
      * Returns an array of all named registered feature gates.
-     * @return {[String]} list of registered features
+     * @return {string[]} list of registered features
      * @type {function}
      */
     function getAllRegisteredFeatures() {

src/utils/StringUtils.js

@@ -44,7 +44,7 @@ define(function (require, exports, module) {
      * Example: var formatted = StringUtils.format("Hello {0}", "World");
      *
      * @param {string} str The base string
-     * @param {...} Arguments to be substituted into the string
+     * @param {rest} Arguments to be substituted into the string
      *
      * @return {string} Formatted string
      */

src/widgets/NotificationUI.js

@@ -180,11 +180,13 @@ define(function (require, exports, module) {
      * // note that you can even provide an HTML Element node with
      * // custom event handlers directly here instead of HTML text.
      * let notification1 = NotificationUI.createFromTemplate(
+     * ```js
      *   "<div>Click me to locate the file in file tree</div>", "showInfileTree",{
      *       allowedPlacements: ['top', 'bottom'],
      *       dismissOnClick: false,
      *       autoCloseTimeS: 300 // auto close the popup after 5 minutes
      *   });
+     * ```
      *
      * @param {string|Element} template A string template or HTML Element to use as the dialog HTML.
      * @param {String} [elementID] optional id string if provided will show the notification pointing to the element.
@@ -307,11 +309,12 @@ define(function (require, exports, module) {
      * // note that you can even provide an HTML Element node with
      * // custom event handlers directly here instead of HTML text.
      * let notification1 = NotificationUI.createToastFromTemplate( "Title here",
+     * ```js
      *   "<div>Click me to locate the file in file tree</div>", {
      *       dismissOnClick: false,
      *       autoCloseTimeS: 300 // auto close the popup after 5 minutes
      *   });
-     *
+     * ```
      * @param {string} title The title for the notification.
      * @param {string|Element} template A string template or HTML Element to use as the dialog HTML.
      * @param {{dismissOnClick, autoCloseTimeS, toastStyle}} [options] optional, supported

src/worker/IndexingWorker.js

@@ -96,10 +96,12 @@ define(function (require, exports, module) {
      * To Execute a named function `extensionName.sayHello` in the worker from phoenix
      * // in my_worker.js. It is a good practice to prefix your `[extensionName]`
      * // to exec handler to prevent name collisions with other extensions.
+     * ```js
      * WorkerComm.setExecHandler("extensionName.sayHello", (arg)=>{
      *     console.log("hello from worker ", arg); // prints "hello from worker phoenix"
      *     return "Hello Phoenix";
-     *   });
+     * });
+     * ```
      * // In Phoenix/extension
      * let workerMessage = await IndexingWorker.execPeer("extensionName.sayHello", "phoenix");
      * console.log(workerMessage); // prints "Hello Phoenix"