@microsoft/api-documenter 7.28.9 → 7.29.0

package/lib-esm/schemas/api-documenter.schema.json

@@ -0,0 +1,47 @@
+{
+  "title": "API Documenter Configuration",
+  "description": "Describes how the API Documenter tool will process a project.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "Part of the JSON Schema standard, this optional keyword declares the URL of the schema that the file conforms to. Editors may download the schema and use it to perform syntax highlighting.",
+      "type": "string"
+    },
+
+    "outputTarget": {
+      "description": "Specifies what type of documentation will be generated",
+      "type": "string",
+      "enum": ["docfx", "markdown"]
+    },
+
+    "newlineKind": {
+      "description": "Specifies what type of newlines API Documenter should use when writing output files.  By default, the output files will be written with Windows-style newlines.  To use POSIX-style newlines, specify \"lf\" instead. To use the OS's default newline kind, specify \"os\".",
+      "type": "string",
+      "enum": ["crlf", "lf", "os"],
+      "default": "crlf"
+    },
+
+    "newDocfxNamespaces": {
+      "description": "This enables an experimental feature that will be officially released with the next major version of API Documenter.  It requires DocFX 2.46 or newer.  It enables documentation for namespaces and adds them to the table of contents.  This will also affect file layout as namespaced items will be nested under a directory for the namespace instead of just within the package.",
+      "type": "boolean"
+    },
+
+    "plugins": {
+      "description": "Specifies plugin packages to be loaded",
+      "type": "array"
+    },
+
+    "tableOfContents": {
+      "description": "Configures how the table of contents is generated.",
+      "type": "object",
+      "additionalProperties": true
+    },
+
+    "showInheritedMembers": {
+      "description": "Specifies whether inherited members should also be shown on an API item's page.",
+      "type": "boolean"
+    }
+  },
+
+  "additionalProperties": false
+}

package/lib-esm/start.js

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import * as os from 'node:os';
+import { PackageJsonLookup } from '@rushstack/node-core-library';
+import { Colorize } from '@rushstack/terminal';
+import { ApiDocumenterCommandLine } from './cli/ApiDocumenterCommandLine';
+const myPackageVersion = PackageJsonLookup.loadOwnPackageJson(__dirname).version;
+console.log(os.EOL +
+    Colorize.bold(`api-documenter ${myPackageVersion} ` + Colorize.cyan(' - https://api-extractor.com/') + os.EOL));
+const parser = new ApiDocumenterCommandLine();
+parser.executeAsync().catch(console.error); // CommandLineParser.executeAsync() should never reject the promise
+//# sourceMappingURL=start.js.map

package/lib-esm/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,MAAM,gBAAgB,GAAW,iBAAiB,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;AAEzF,OAAO,CAAC,GAAG,CACT,EAAE,CAAC,GAAG;IACJ,QAAQ,CAAC,IAAI,CACX,kBAAkB,gBAAgB,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,+BAA+B,CAAC,GAAG,EAAE,CAAC,GAAG,CAChG,CACJ,CAAC;AAEF,MAAM,MAAM,GAA6B,IAAI,wBAAwB,EAAE,CAAC;AAExE,MAAM,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,mEAAmE","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as os from 'node:os';\n\nimport { PackageJsonLookup } from '@rushstack/node-core-library';\nimport { Colorize } from '@rushstack/terminal';\n\nimport { ApiDocumenterCommandLine } from './cli/ApiDocumenterCommandLine';\n\nconst myPackageVersion: string = PackageJsonLookup.loadOwnPackageJson(__dirname).version;\n\nconsole.log(\n  os.EOL +\n    Colorize.bold(\n      `api-documenter ${myPackageVersion} ` + Colorize.cyan(' - https://api-extractor.com/') + os.EOL\n    )\n);\n\nconst parser: ApiDocumenterCommandLine = new ApiDocumenterCommandLine();\n\nparser.executeAsync().catch(console.error); // CommandLineParser.executeAsync() should never reject the promise\n"]}

package/lib-esm/utils/IndentedWriter.js

@@ -0,0 +1,235 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { StringBuilder } from '@rushstack/node-core-library';
+/**
+ * A utility for writing indented text.
+ *
+ * @remarks
+ *
+ * Note that the indentation is inserted at the last possible opportunity.
+ * For example, this code...
+ *
+ * ```ts
+ *   writer.write('begin\n');
+ *   writer.increaseIndent();
+ *   writer.write('one\ntwo\n');
+ *   writer.decreaseIndent();
+ *   writer.increaseIndent();
+ *   writer.decreaseIndent();
+ *   writer.write('end');
+ * ```
+ *
+ * ...would produce this output:
+ *
+ * ```
+ *   begin
+ *     one
+ *     two
+ *   end
+ * ```
+ */
+export class IndentedWriter {
+    constructor(builder) {
+        /**
+         * The text characters used to create one level of indentation.
+         * Two spaces by default.
+         */
+        this.defaultIndentPrefix = '  ';
+        this._builder = builder === undefined ? new StringBuilder() : builder;
+        this._latestChunk = undefined;
+        this._previousChunk = undefined;
+        this._atStartOfLine = true;
+        this._indentStack = [];
+        this._indentText = '';
+        this._beforeStack = [];
+        this._isWritingBeforeStack = false;
+    }
+    /**
+     * Retrieves the output that was built so far.
+     */
+    getText() {
+        return this._builder.toString();
+    }
+    toString() {
+        return this.getText();
+    }
+    /**
+     * Increases the indentation.  Normally the indentation is two spaces,
+     * however an arbitrary prefix can optional be specified.  (For example,
+     * the prefix could be "// " to indent and comment simultaneously.)
+     * Each call to IndentedWriter.increaseIndent() must be followed by a
+     * corresponding call to IndentedWriter.decreaseIndent().
+     */
+    increaseIndent(indentPrefix) {
+        this._indentStack.push(indentPrefix !== undefined ? indentPrefix : this.defaultIndentPrefix);
+        this._updateIndentText();
+    }
+    /**
+     * Decreases the indentation, reverting the effect of the corresponding call
+     * to IndentedWriter.increaseIndent().
+     */
+    decreaseIndent() {
+        this._indentStack.pop();
+        this._updateIndentText();
+    }
+    /**
+     * A shorthand for ensuring that increaseIndent()/decreaseIndent() occur
+     * in pairs.
+     */
+    indentScope(scope, indentPrefix) {
+        this.increaseIndent(indentPrefix);
+        scope();
+        this.decreaseIndent();
+    }
+    /**
+     * Adds a newline if the file pointer is not already at the start of the line (or start of the stream).
+     */
+    ensureNewLine() {
+        const lastCharacter = this.peekLastCharacter();
+        if (lastCharacter !== '\n' && lastCharacter !== '') {
+            this._writeNewLine();
+        }
+    }
+    /**
+     * Adds up to two newlines to ensure that there is a blank line above the current line.
+     */
+    ensureSkippedLine() {
+        if (this.peekLastCharacter() !== '\n') {
+            this._writeNewLine();
+        }
+        const secondLastCharacter = this.peekSecondLastCharacter();
+        if (secondLastCharacter !== '\n' && secondLastCharacter !== '') {
+            this._writeNewLine();
+        }
+    }
+    /**
+     * Returns the last character that was written, or an empty string if no characters have been written yet.
+     */
+    peekLastCharacter() {
+        if (this._latestChunk !== undefined) {
+            return this._latestChunk.substr(-1, 1);
+        }
+        return '';
+    }
+    /**
+     * Returns the second to last character that was written, or an empty string if less than one characters
+     * have been written yet.
+     */
+    peekSecondLastCharacter() {
+        if (this._latestChunk !== undefined) {
+            if (this._latestChunk.length > 1) {
+                return this._latestChunk.substr(-2, 1);
+            }
+            if (this._previousChunk !== undefined) {
+                return this._previousChunk.substr(-1, 1);
+            }
+        }
+        return '';
+    }
+    /**
+     * Writes `before` and `after` messages if and only if `mayWrite` writes anything.
+     *
+     * If `mayWrite` writes "CONTENT", this method will write "<before>CONTENT<after>".
+     * If `mayWrite` writes nothing, this method will write nothing.
+     */
+    writeTentative(before, after, mayWrite) {
+        this._beforeStack.push(before);
+        // If this function writes anything, then _all_ messages in the "before stack" will also be
+        // written. This means that the stack will be empty (as when we write a message from the stack,
+        // we remove it from the stack).
+        mayWrite();
+        // If the stack is not empty, it means that `mayWrite` didn't write anything. Pop the last-
+        // added message from the stack, we'll never write it. Otherwise, if the stack is empty, then
+        // write the "after" message.
+        if (this._beforeStack.length > 0) {
+            this._beforeStack.pop();
+        }
+        else {
+            this.write(after);
+        }
+    }
+    /**
+     * Writes some text to the internal string buffer, applying indentation according
+     * to the current indentation level.  If the string contains multiple newlines,
+     * each line will be indented separately.
+     */
+    write(message) {
+        if (message.length === 0) {
+            return;
+        }
+        if (!this._isWritingBeforeStack) {
+            this._writeBeforeStack();
+        }
+        // If there are no newline characters, then append the string verbatim
+        if (!/[\r\n]/.test(message)) {
+            this._writeLinePart(message);
+            return;
+        }
+        // Otherwise split the lines and write each one individually
+        let first = true;
+        for (const linePart of message.split('\n')) {
+            if (!first) {
+                this._writeNewLine();
+            }
+            else {
+                first = false;
+            }
+            if (linePart) {
+                this._writeLinePart(linePart.replace(/[\r]/g, ''));
+            }
+        }
+    }
+    /**
+     * A shorthand for writing an optional message, followed by a newline.
+     * Indentation is applied following the semantics of IndentedWriter.write().
+     */
+    writeLine(message = '') {
+        if (message.length > 0) {
+            this.write(message);
+        }
+        else if (!this._isWritingBeforeStack) {
+            this._writeBeforeStack();
+        }
+        this._writeNewLine();
+    }
+    /**
+     * Writes a string that does not contain any newline characters.
+     */
+    _writeLinePart(message) {
+        if (message.length > 0) {
+            if (this._atStartOfLine && this._indentText.length > 0) {
+                this._write(this._indentText);
+            }
+            this._write(message);
+            this._atStartOfLine = false;
+        }
+    }
+    _writeNewLine() {
+        if (this._atStartOfLine && this._indentText.length > 0) {
+            this._write(this._indentText);
+        }
+        this._write('\n');
+        this._atStartOfLine = true;
+    }
+    _write(s) {
+        this._previousChunk = this._latestChunk;
+        this._latestChunk = s;
+        this._builder.append(s);
+    }
+    /**
+     * Writes all messages in our before stack, processing them in FIFO order. This stack is
+     * populated by the `writeTentative` method.
+     */
+    _writeBeforeStack() {
+        this._isWritingBeforeStack = true;
+        for (const message of this._beforeStack) {
+            this.write(message);
+        }
+        this._isWritingBeforeStack = false;
+        this._beforeStack = [];
+    }
+    _updateIndentText() {
+        this._indentText = this._indentStack.join('');
+    }
+}
+//# sourceMappingURL=IndentedWriter.js.map

package/lib-esm/utils/IndentedWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndentedWriter.js","sourceRoot":"","sources":["../../src/utils/IndentedWriter.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport { StringBuilder, type IStringBuilder } from '@rushstack/node-core-library';\n\n/**\n * A utility for writing indented text.\n *\n * @remarks\n *\n * Note that the indentation is inserted at the last possible opportunity.\n * For example, this code...\n *\n * ```ts\n *   writer.write('begin\\n');\n *   writer.increaseIndent();\n *   writer.write('one\\ntwo\\n');\n *   writer.decreaseIndent();\n *   writer.increaseIndent();\n *   writer.decreaseIndent();\n *   writer.write('end');\n * ```\n *\n * ...would produce this output:\n *\n * ```\n *   begin\n *     one\n *     two\n *   end\n * ```\n */\nexport class IndentedWriter {\n  /**\n   * The text characters used to create one level of indentation.\n   * Two spaces by default.\n   */\n  public defaultIndentPrefix: string = '  ';\n\n  private readonly _builder: IStringBuilder;\n\n  private _latestChunk: string | undefined;\n  private _previousChunk: string | undefined;\n  private _atStartOfLine: boolean;\n\n  private readonly _indentStack: string[];\n  private _indentText: string;\n\n  private _beforeStack: string[];\n  private _isWritingBeforeStack: boolean;\n\n  public constructor(builder?: IStringBuilder) {\n    this._builder = builder === undefined ? new StringBuilder() : builder;\n\n    this._latestChunk = undefined;\n    this._previousChunk = undefined;\n    this._atStartOfLine = true;\n\n    this._indentStack = [];\n    this._indentText = '';\n\n    this._beforeStack = [];\n    this._isWritingBeforeStack = false;\n  }\n\n  /**\n   * Retrieves the output that was built so far.\n   */\n  public getText(): string {\n    return this._builder.toString();\n  }\n\n  public toString(): string {\n    return this.getText();\n  }\n\n  /**\n   * Increases the indentation.  Normally the indentation is two spaces,\n   * however an arbitrary prefix can optional be specified.  (For example,\n   * the prefix could be \"// \" to indent and comment simultaneously.)\n   * Each call to IndentedWriter.increaseIndent() must be followed by a\n   * corresponding call to IndentedWriter.decreaseIndent().\n   */\n  public increaseIndent(indentPrefix?: string): void {\n    this._indentStack.push(indentPrefix !== undefined ? indentPrefix : this.defaultIndentPrefix);\n    this._updateIndentText();\n  }\n\n  /**\n   * Decreases the indentation, reverting the effect of the corresponding call\n   * to IndentedWriter.increaseIndent().\n   */\n  public decreaseIndent(): void {\n    this._indentStack.pop();\n    this._updateIndentText();\n  }\n\n  /**\n   * A shorthand for ensuring that increaseIndent()/decreaseIndent() occur\n   * in pairs.\n   */\n  public indentScope(scope: () => void, indentPrefix?: string): void {\n    this.increaseIndent(indentPrefix);\n    scope();\n    this.decreaseIndent();\n  }\n\n  /**\n   * Adds a newline if the file pointer is not already at the start of the line (or start of the stream).\n   */\n  public ensureNewLine(): void {\n    const lastCharacter: string = this.peekLastCharacter();\n    if (lastCharacter !== '\\n' && lastCharacter !== '') {\n      this._writeNewLine();\n    }\n  }\n\n  /**\n   * Adds up to two newlines to ensure that there is a blank line above the current line.\n   */\n  public ensureSkippedLine(): void {\n    if (this.peekLastCharacter() !== '\\n') {\n      this._writeNewLine();\n    }\n\n    const secondLastCharacter: string = this.peekSecondLastCharacter();\n    if (secondLastCharacter !== '\\n' && secondLastCharacter !== '') {\n      this._writeNewLine();\n    }\n  }\n\n  /**\n   * Returns the last character that was written, or an empty string if no characters have been written yet.\n   */\n  public peekLastCharacter(): string {\n    if (this._latestChunk !== undefined) {\n      return this._latestChunk.substr(-1, 1);\n    }\n    return '';\n  }\n\n  /**\n   * Returns the second to last character that was written, or an empty string if less than one characters\n   * have been written yet.\n   */\n  public peekSecondLastCharacter(): string {\n    if (this._latestChunk !== undefined) {\n      if (this._latestChunk.length > 1) {\n        return this._latestChunk.substr(-2, 1);\n      }\n      if (this._previousChunk !== undefined) {\n        return this._previousChunk.substr(-1, 1);\n      }\n    }\n    return '';\n  }\n\n  /**\n   * Writes `before` and `after` messages if and only if `mayWrite` writes anything.\n   *\n   * If `mayWrite` writes \"CONTENT\", this method will write \"<before>CONTENT<after>\".\n   * If `mayWrite` writes nothing, this method will write nothing.\n   */\n  public writeTentative(before: string, after: string, mayWrite: () => void): void {\n    this._beforeStack.push(before);\n\n    // If this function writes anything, then _all_ messages in the \"before stack\" will also be\n    // written. This means that the stack will be empty (as when we write a message from the stack,\n    // we remove it from the stack).\n    mayWrite();\n\n    // If the stack is not empty, it means that `mayWrite` didn't write anything. Pop the last-\n    // added message from the stack, we'll never write it. Otherwise, if the stack is empty, then\n    // write the \"after\" message.\n    if (this._beforeStack.length > 0) {\n      this._beforeStack.pop();\n    } else {\n      this.write(after);\n    }\n  }\n\n  /**\n   * Writes some text to the internal string buffer, applying indentation according\n   * to the current indentation level.  If the string contains multiple newlines,\n   * each line will be indented separately.\n   */\n  public write(message: string): void {\n    if (message.length === 0) {\n      return;\n    }\n\n    if (!this._isWritingBeforeStack) {\n      this._writeBeforeStack();\n    }\n\n    // If there are no newline characters, then append the string verbatim\n    if (!/[\\r\\n]/.test(message)) {\n      this._writeLinePart(message);\n      return;\n    }\n\n    // Otherwise split the lines and write each one individually\n    let first: boolean = true;\n    for (const linePart of message.split('\\n')) {\n      if (!first) {\n        this._writeNewLine();\n      } else {\n        first = false;\n      }\n      if (linePart) {\n        this._writeLinePart(linePart.replace(/[\\r]/g, ''));\n      }\n    }\n  }\n\n  /**\n   * A shorthand for writing an optional message, followed by a newline.\n   * Indentation is applied following the semantics of IndentedWriter.write().\n   */\n  public writeLine(message: string = ''): void {\n    if (message.length > 0) {\n      this.write(message);\n    } else if (!this._isWritingBeforeStack) {\n      this._writeBeforeStack();\n    }\n\n    this._writeNewLine();\n  }\n\n  /**\n   * Writes a string that does not contain any newline characters.\n   */\n  private _writeLinePart(message: string): void {\n    if (message.length > 0) {\n      if (this._atStartOfLine && this._indentText.length > 0) {\n        this._write(this._indentText);\n      }\n      this._write(message);\n      this._atStartOfLine = false;\n    }\n  }\n\n  private _writeNewLine(): void {\n    if (this._atStartOfLine && this._indentText.length > 0) {\n      this._write(this._indentText);\n    }\n\n    this._write('\\n');\n    this._atStartOfLine = true;\n  }\n\n  private _write(s: string): void {\n    this._previousChunk = this._latestChunk;\n    this._latestChunk = s;\n    this._builder.append(s);\n  }\n\n  /**\n   * Writes all messages in our before stack, processing them in FIFO order. This stack is\n   * populated by the `writeTentative` method.\n   */\n  private _writeBeforeStack(): void {\n    this._isWritingBeforeStack = true;\n\n    for (const message of this._beforeStack) {\n      this.write(message);\n    }\n\n    this._isWritingBeforeStack = false;\n    this._beforeStack = [];\n  }\n\n  private _updateIndentText(): void {\n    this._indentText = this._indentStack.join('');\n  }\n}\n"]}

package/lib-esm/utils/ToSdpConvertHelper.js

@@ -0,0 +1,338 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import path from 'node:path';
+import { FileSystem, Encoding, NewlineKind } from '@rushstack/node-core-library';
+export function convertUDPYamlToSDP(folderPath) {
+    convert(folderPath, folderPath);
+}
+function convert(inputPath, outputPath) {
+    console.log();
+    if (!FileSystem.exists(inputPath)) {
+        console.error(`input path: ${inputPath} is not exist`);
+        return;
+    }
+    FileSystem.readFolderItemNames(inputPath).forEach((name) => {
+        const fpath = path.join(inputPath, name);
+        if (FileSystem.getStatistics(fpath).isFile()) {
+            // only convert yaml
+            if (!name.endsWith('.yml')) {
+                return;
+            }
+            // parse file
+            const yamlContent = FileSystem.readFile(fpath, { encoding: Encoding.Utf8 });
+            // only convert universalreference yaml
+            const isLegacyYaml = yamlContent.startsWith('### YamlMime:UniversalReference');
+            if (!isLegacyYaml) {
+                return;
+            }
+            console.log(`convert file ${fpath} from udp to sdp`);
+            const file = yaml.load(yamlContent);
+            const result = convertToSDP(file);
+            if (result && result.model) {
+                const stringified = `### YamlMime:TS${result.type}\n${yaml.dump(result.model, {
+                    lineWidth: 120
+                })}`;
+                FileSystem.writeFile(`${outputPath}/${name}`, stringified, {
+                    convertLineEndings: NewlineKind.CrLf,
+                    ensureFolderExists: true
+                });
+            }
+            else {
+                console.log('not target file ', fpath);
+            }
+        }
+        else {
+            // read contents
+            convert(fpath, path.join(outputPath, name));
+        }
+    });
+}
+function convertToPackageSDP(transfomredClass) {
+    const element = transfomredClass.items[0];
+    const packageModel = {
+        uid: element.uid,
+        name: element.name,
+        type: 'package'
+    };
+    if (element.summary) {
+        packageModel.summary = element.summary;
+    }
+    else {
+        packageModel.summary = '';
+    }
+    // search in children
+    if (element.children) {
+        element.children.forEach((child) => {
+            if (child.endsWith(':class')) {
+                assignPackageModelFields(packageModel, 'classes', child);
+            }
+            else if (child.endsWith(':interface')) {
+                assignPackageModelFields(packageModel, 'interfaces', child);
+            }
+            else if (child.endsWith(':enum')) {
+                assignPackageModelFields(packageModel, 'enums', child);
+            }
+            else if (child.endsWith(':type')) {
+                assignPackageModelFields(packageModel, 'typeAliases', child);
+            }
+            else {
+                // console.log("other type: ", child)
+            }
+        });
+    }
+    for (let i = 1; i < transfomredClass.items.length; i++) {
+        const ele = transfomredClass.items[i];
+        switch (ele.type) {
+            case 'typealias':
+                // need generate typeAlias file for this
+                break;
+            case 'function':
+                if (!packageModel.functions) {
+                    packageModel.functions = [];
+                }
+                packageModel.functions.push(convertToFunctionSDP(ele, element.uid, transfomredClass));
+                break;
+            default:
+                // console.log(transfomredClass.items[0].name)
+                console.log('[warning] not applied type(package): ', ele.type);
+        }
+    }
+    return packageModel;
+}
+function assignPackageModelFields(packageModel, name, uid) {
+    if (!packageModel[name]) {
+        packageModel[name] = [];
+    }
+    packageModel[name].push(uid);
+}
+function convertToSDP(transfomredClass) {
+    const element = transfomredClass.items[0];
+    switch (element.type) {
+        case 'class':
+        case 'interface':
+            return {
+                model: convertToTypeSDP(transfomredClass, element.type === 'class'),
+                type: 'Type'
+            };
+        case 'enum':
+            if (transfomredClass.items.length < 2) {
+                console.log(`[warning] enum ${element.uid}/${element.name} does not have fields`);
+                return undefined;
+            }
+            return { model: convertToEnumSDP(transfomredClass), type: 'Enum' };
+        case 'typealias':
+            return { model: convertToTypeAliasSDP(element, transfomredClass), type: 'TypeAlias' };
+        case 'package':
+            return {
+                model: convertToPackageSDP(transfomredClass),
+                type: 'Package'
+            };
+        default:
+            console.log('not applied type: ', element.type);
+            return undefined;
+    }
+}
+function convertToEnumSDP(transfomredClass) {
+    const element = transfomredClass.items[0];
+    const fields = [];
+    for (let i = 1; i < transfomredClass.items.length; i++) {
+        const ele = transfomredClass.items[i];
+        const field = {
+            name: ele.name,
+            uid: ele.uid,
+            package: element.package
+        };
+        if (ele.summary) {
+            field.summary = ele.summary;
+        }
+        else {
+            field.summary = '';
+        }
+        if (ele.numericValue) {
+            field.value = ele.numericValue;
+        }
+        fields.push(field);
+    }
+    const result = {
+        ...convertCommonYamlModel(element, element.package, transfomredClass),
+        fields: fields
+    };
+    return result;
+}
+function convertToTypeAliasSDP(element, transfomredClass) {
+    const result = {
+        ...convertCommonYamlModel(element, element.package, transfomredClass)
+    };
+    if (element.syntax) {
+        result.syntax = element.syntax.content;
+    }
+    return result;
+}
+function convertToTypeSDP(transfomredClass, isClass) {
+    const element = transfomredClass.items[0];
+    const constructors = [];
+    const properties = [];
+    const methods = [];
+    const events = [];
+    for (let i = 1; i < transfomredClass.items.length; i++) {
+        const ele = transfomredClass.items[i];
+        const item = convertCommonYamlModel(ele, element.package, transfomredClass);
+        if (ele.type === 'constructor') {
+            // interface does not need this field
+            if (isClass) {
+                constructors.push(item);
+            }
+        }
+        else if (ele.type === 'property') {
+            properties.push(item);
+        }
+        else if (ele.type === 'method') {
+            methods.push(item);
+        }
+        else if (ele.type === 'event') {
+            events.push(item);
+        }
+        else {
+            console.log(`[warning] ${ele.uid}#${ele.name} is not applied sub type ${ele.type} for type yaml`);
+        }
+    }
+    const result = {
+        ...convertCommonYamlModel(element, element.package, transfomredClass),
+        type: isClass ? 'class' : 'interface'
+    };
+    delete result.syntax;
+    if (constructors.length > 0) {
+        result.constructors = constructors;
+    }
+    if (properties.length > 0) {
+        result.properties = properties;
+    }
+    if (methods.length > 0) {
+        result.methods = methods;
+    }
+    if (events.length > 0) {
+        result.events = events;
+    }
+    if (element.extends && element.extends.length > 0) {
+        result.extends = convertSelfTypeToXref(element.extends[0], transfomredClass);
+    }
+    return result;
+}
+function convertToFunctionSDP(element, packageName, transfomredClass) {
+    const model = convertCommonYamlModel(element, packageName, transfomredClass);
+    // don't need these fields
+    delete model.fullName;
+    return model;
+}
+function convertCommonYamlModel(element, packageName, transfomredClass) {
+    var _a;
+    const result = {
+        name: element.name,
+        uid: element.uid,
+        package: packageName
+    };
+    if (element.fullName) {
+        result.fullName = element.fullName;
+    }
+    if (element.summary) {
+        result.summary = element.summary;
+    }
+    else {
+        result.summary = '';
+    }
+    // because mustache meet same variable in different level
+    // such as: { "pre": true, "list": [{}]}
+    // if item in list wants to use pre but the pre is not assigned, it will use outer pre field.
+    // so, there need to set below variable explict
+    if (element.remarks) {
+        result.remarks = element.remarks;
+    }
+    else {
+        result.remarks = '';
+    }
+    if (element.example) {
+        result.example = element.example;
+    }
+    else {
+        result.example = [];
+    }
+    result.isPreview = element.isPreview;
+    if (!result.isPreview) {
+        result.isPreview = false;
+    }
+    if (element.deprecated) {
+        result.isDeprecated = true;
+        result.customDeprecatedMessage = element.deprecated.content;
+    }
+    else {
+        result.isDeprecated = false;
+    }
+    if (element.syntax) {
+        result.syntax = {};
+        const syntax = element.syntax;
+        result.syntax.content = syntax.content;
+        if (syntax.parameters && syntax.parameters.length > 0) {
+            (_a = syntax.parameters) === null || _a === void 0 ? void 0 : _a.forEach((it) => {
+                delete it.optional;
+                delete it.defaultValue;
+            });
+            result.syntax.parameters = syntax.parameters.map((it) => {
+                return {
+                    ...it,
+                    id: it.id,
+                    type: convertSelfTypeToXref(escapeMarkdown(it.type[0]), transfomredClass)
+                };
+            });
+        }
+        if (syntax.return) {
+            result.syntax.return = {
+                ...syntax.return,
+                type: convertSelfTypeToXref(escapeMarkdown(syntax.return.type[0]), transfomredClass)
+            };
+        }
+    }
+    return result;
+}
+function escapeMarkdown(name) {
+    // eg: [key: string]: string
+    const markdownLinkRegEx = /^\s*(\[.+\]):(.+)/g;
+    return name.replace(markdownLinkRegEx, `$1\\:$2`);
+}
+function convertSelfTypeToXref(name, transfomredClass) {
+    var _a, _b, _c;
+    let result = name;
+    // if complex type, need to get real type from references
+    if (result.endsWith(':complex')) {
+        const specs = (_b = (_a = transfomredClass.references) === null || _a === void 0 ? void 0 : _a.find((item) => {
+            return item.uid === name;
+        })) === null || _b === void 0 ? void 0 : _b['spec.typeScript'];
+        if (specs && specs.length > 0) {
+            result = '';
+            for (const spec of specs) {
+                // start with ! will be node base type
+                if (spec.uid && !spec.uid.startsWith('!')) {
+                    result += spec.uid;
+                }
+                else {
+                    result += spec.name;
+                }
+            }
+        }
+    }
+    else if (result.startsWith('!')) {
+        // uid: '!Object:interface'
+        // name: Object
+        // start with !, not complex type, use reference name directly
+        const ref = (_c = transfomredClass.references) === null || _c === void 0 ? void 0 : _c.find((item) => {
+            return item.uid === name;
+        });
+        if (ref && ref.name) {
+            result = ref.name;
+        }
+    }
+    // parse < >
+    result = result.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const uidRegEx = /(@?[\w\d\-/!~\.]+\:[\w\d\-\(/]+)/g;
+    return result.replace(uidRegEx, `<xref uid="$1" />`);
+}
+//# sourceMappingURL=ToSdpConvertHelper.js.map