Add XML Parsing with DocXmlElement

common/changes/@microsoft/tsdoc-config/feat-docxmlnodes_2022-08-03-21-34.json

@@ -0,0 +1,11 @@
+{
+ "changes": [
+ {
+ "packageName": "@microsoft/tsdoc-config",
+ "comment": "(BREAKING SCHEMA CHANGE) Rename tsdoc.json fields: \"supportedHtmlElements\" renamed to \"supportedXmlElements\"; \"reportUnsupportedHtmlElements\" renamed to \"reportUnsupportedXmlElements\"",
+ "type": "minor"
+ }
+ ],
+ "packageName": "@microsoft/tsdoc-config",
+ "email": "[email protected]"
+}

common/changes/@microsoft/tsdoc-config/feat-docxmlnodes_2022-08-03-21-35.json

@@ -0,0 +1,11 @@
+{
+ "changes": [
+ {
+ "packageName": "@microsoft/tsdoc-config",
+ "comment": "(BREAKING API CHANGE) Rename several APIs to use the name \"Xml\" instead of \"Html\". For example, TSDocConfigFile.addSupportedHtmlElement() was renamed to TSDocConfigFile.addSupportedXmlElement().",
+ "type": "minor"
+ }
+ ],
+ "packageName": "@microsoft/tsdoc-config",
+ "email": "[email protected]"
+}

common/changes/@microsoft/tsdoc/feat-docxmlnodes_2022-08-03-21-34.json

@@ -0,0 +1,11 @@
+{
+ "changes": [
+ {
+ "packageName": "@microsoft/tsdoc",
+ "comment": "(BREAKING API CHANGE) Replace AST nodes `DocHtmlStartTag` and `DocHtmlEndTag` with a new node `DocXmlElement` that represents a hierarchical DOM tree",
+ "type": "minor"
+ }
+ ],
+ "packageName": "@microsoft/tsdoc",
+ "email": "[email protected]"
+}

common/changes/@microsoft/tsdoc/feat-docxmlnodes_2022-08-03-21-35.json

@@ -0,0 +1,11 @@
+{
+ "changes": [
+ {
+ "packageName": "@microsoft/tsdoc",
+ "comment": "(BREAKING SYNTAX CHANGE) Improve the parser to report syntax errors if opening/closing XML tags are not correctly matched",
+ "type": "minor"
+ }
+ ],
+ "packageName": "@microsoft/tsdoc",
+ "email": "[email protected]"
+}

playground/src/SyntaxStyler/DocNodeSyntaxStyler.ts

@@ -72,11 +72,11 @@ export class DocNodeSyntaxStyler {
  case 'DocMemberSymbol_RightBracket':
  case 'FencedCode_ClosingFence':
  case 'FencedCode_OpeningFence':
- case 'HtmlAttribute_Equals':
- case 'HtmlEndTag_ClosingDelimiter':
- case 'HtmlEndTag_OpeningDelimiter':
- case 'HtmlStartTag_ClosingDelimiter':
- case 'HtmlStartTag_OpeningDelimiter':
+ case 'XmlAttribute_Equals':
+ case 'XmlEndTag_ClosingDelimiter':
+ case 'XmlEndTag_OpeningDelimiter':
+ case 'XmlStartTag_ClosingDelimiter':
+ case 'XmlStartTag_OpeningDelimiter':
  case 'InlineTag_ClosingDelimiter':
  case 'InlineTag_OpeningDelimiter':
  case 'LinkTag_Pipe':
@@ -155,24 +155,25 @@ export class DocNodeSyntaxStyler {
  break;
  }
 
- case 'HtmlEndTag_Name':
- case 'HtmlStartTag_Name': {
+ case 'XmlElement_Name':
+ case 'XmlEndTag_Name':
+ case 'XmlStartTag_Name': {
  DocNodeSyntaxStyler._addTokenStyles(styles, docNode.content, {
  theme,
  styleTokens: [...styleTokens, 'element', 'name']
  });
  break;
  }
 
- case 'HtmlAttribute_Name': {
+ case 'XmlAttribute_Name': {
  DocNodeSyntaxStyler._addTokenStyles(styles, docNode.content, {
  theme,
  styleTokens: [...styleTokens, 'element', 'attribute', 'name']
  });
  break;
  }
 
- case 'HtmlAttribute_Value': {
+ case 'XmlAttribute_Value': {
  DocNodeSyntaxStyler._addTokenStyles(styles, docNode.content, {
  theme,
  styleTokens: [...styleTokens, 'element', 'attribute', 'value']

tsdoc-config/src/TSDocConfigFile.ts

@@ -41,8 +41,8 @@ interface IConfigJson {
  noStandardTags?: boolean;
  tagDefinitions?: ITagConfigJson[];
  supportForTags?: { [tagName: string]: boolean };
- supportedHtmlElements?: string[];
- reportUnsupportedHtmlElements?: boolean;
+ supportedXmlElements?: string[];
+ reportUnsupportedXmlElements?: boolean;
 }
 
 /**
@@ -71,8 +71,8 @@ export class TSDocConfigFile {
  private readonly _tagDefinitions: TSDocTagDefinition[];
  private readonly _tagDefinitionNames: Set<string>;
  private readonly _supportForTags: Map<string, boolean>;
- private _supportedHtmlElements: Set<string> | undefined;
- private _reportUnsupportedHtmlElements: boolean | undefined;
+ private _supportedXmlElements: Set<string> | undefined;
+ private _reportUnsupportedXmlElements: boolean | undefined;
 
  private constructor() {
  this.log = new ParserMessageLog();
@@ -171,16 +171,16 @@ export class TSDocConfigFile {
  return this._supportForTags;
  }
 
- public get supportedHtmlElements(): ReadonlyArray<string> | undefined {
- return this._supportedHtmlElements && Array.from(this._supportedHtmlElements);
+ public get supportedXmlElements(): ReadonlyArray<string> | undefined {
+ return this._supportedXmlElements && Array.from(this._supportedXmlElements);
  }
 
- public get reportUnsupportedHtmlElements(): boolean | undefined {
- return this._reportUnsupportedHtmlElements;
+ public get reportUnsupportedXmlElements(): boolean | undefined {
+ return this._reportUnsupportedXmlElements;
  }
 
- public set reportUnsupportedHtmlElements(value: boolean | undefined) {
- this._reportUnsupportedHtmlElements = value;
+ public set reportUnsupportedXmlElements(value: boolean | undefined) {
+ this._reportUnsupportedXmlElements = value;
  }
 
  /**
@@ -234,20 +234,20 @@ export class TSDocConfigFile {
  }
 
  /**
- * Adds a new item to the `supportedHtmlElements` array.
+ * Adds a new item to the `supportedXmlElements` array.
  */
- public addSupportedHtmlElement(htmlElement: string): void {
- if (!this._supportedHtmlElements) {
- this._supportedHtmlElements = new Set();
+ public addSupportedXmlElement(xmlElement: string): void {
+ if (!this._supportedXmlElements) {
+ this._supportedXmlElements = new Set();
  }
- this._supportedHtmlElements.add(htmlElement);
+ this._supportedXmlElements.add(xmlElement);
  }
 
  /**
- * Removes the explicit list of allowed html elements.
+ * Removes the explicit list of allowed xml elements.
  */
- public clearSupportedHtmlElements(): void {
- this._supportedHtmlElements = undefined;
+ public clearSupportedXmlElements(): void {
+ this._supportedXmlElements = undefined;
  }
 
  /**
@@ -367,14 +367,14 @@ export class TSDocConfigFile {
  });
  }
 
- if (configJson.supportedHtmlElements) {
- this._supportedHtmlElements = new Set();
- for (const htmlElement of configJson.supportedHtmlElements) {
- this.addSupportedHtmlElement(htmlElement);
+ if (configJson.supportedXmlElements) {
+ this._supportedXmlElements = new Set();
+ for (const xmlElement of configJson.supportedXmlElements) {
+ this.addSupportedXmlElement(xmlElement);
  }
  }
 
- this._reportUnsupportedHtmlElements = configJson.reportUnsupportedHtmlElements;
+ this._reportUnsupportedXmlElements = configJson.reportUnsupportedXmlElements;
 
  if (configJson.supportForTags) {
  for (const tagName of Object.keys(configJson.supportForTags)) {
@@ -595,11 +595,11 @@ export class TSDocConfigFile {
  configFile.setSupportForTag(tagDefinition.tagName, true);
  }
 
- for (const htmlElement of configuration.supportedHtmlElements) {
- configFile.addSupportedHtmlElement(htmlElement);
+ for (const xmlElement of configuration.supportedXmlElements) {
+ configFile.addSupportedXmlElement(xmlElement);
  }
 
- configFile.reportUnsupportedHtmlElements = configuration.validation.reportUnsupportedHtmlElements;
+ configFile.reportUnsupportedXmlElements = configuration.validation.reportUnsupportedXmlElements;
 
  return configFile;
  }
@@ -639,12 +639,12 @@ export class TSDocConfigFile {
  });
  }
 
- if (this.supportedHtmlElements) {
- configJson.supportedHtmlElements = [...this.supportedHtmlElements];
+ if (this.supportedXmlElements) {
+ configJson.supportedXmlElements = [...this.supportedXmlElements];
  }
 
- if (this._reportUnsupportedHtmlElements !== undefined) {
- configJson.reportUnsupportedHtmlElements = this._reportUnsupportedHtmlElements;
+ if (this._reportUnsupportedXmlElements !== undefined) {
+ configJson.reportUnsupportedXmlElements = this._reportUnsupportedXmlElements;
  }
 
  return configJson;
@@ -769,14 +769,14 @@ export class TSDocConfigFile {
  }
  });
 
- if (this.supportedHtmlElements) {
- configuration.setSupportedHtmlElements([...this.supportedHtmlElements]);
+ if (this.supportedXmlElements) {
+ configuration.setSupportedXmlElements([...this.supportedXmlElements]);
  }
 
- if (this._reportUnsupportedHtmlElements === false) {
- configuration.validation.reportUnsupportedHtmlElements = false;
- } else if (this._reportUnsupportedHtmlElements === true) {
- configuration.validation.reportUnsupportedHtmlElements = true;
+ if (this._reportUnsupportedXmlElements === false) {
+ configuration.validation.reportUnsupportedXmlElements = false;
+ } else if (this._reportUnsupportedXmlElements === true) {
+ configuration.validation.reportUnsupportedXmlElements = true;
  }
  }