feat(csharp): XML encode contents of <summary> and <example><code> co…

…de comments (#4785)

* fix(csharp): XML encode contents of <summary> and <example><code> code comments

generators/csharp/codegen/src/ast/Class.ts

@@ -5,6 +5,7 @@ import { ClassInstantiation } from "./ClassInstantiation";
 import { ClassReference } from "./ClassReference";
 import { CodeBlock } from "./CodeBlock";
 import { AstNode } from "./core/AstNode";
+import { DocXmlWriter } from "./core/DocXmlWriter";
 import { Writer } from "./core/Writer";
 import { Field } from "./Field";
 import { Interface } from "./Interface";
@@ -168,11 +169,8 @@ export class Class extends AstNode {
         }
 
         if (this.summary != null) {
-            writer.writeLine("/// <summary>");
-            this.summary.split("\n").forEach((line) => {
-                writer.writeLine(`/// ${line}`);
-            });
-            writer.writeLine("/// </summary>");
+            const docXmlWriter = new DocXmlWriter(writer);
+            docXmlWriter.writeNodeWithEscaping("summary", this.summary);
         }
         if (this.annotations.length > 0) {
             writer.write("[");

generators/csharp/codegen/src/ast/Field.ts

@@ -3,6 +3,7 @@ import { Annotation } from "./Annotation";
 import { ClassReference } from "./ClassReference";
 import { CodeBlock } from "./CodeBlock";
 import { AstNode } from "./core/AstNode";
+import { DocXmlWriter } from "./core/DocXmlWriter";
 import { Writer } from "./core/Writer";
 import { Type } from "./Type";
 
@@ -108,11 +109,8 @@ export class Field extends AstNode {
 
     public write(writer: Writer): void {
         if (this.summary != null) {
-            writer.writeLine("/// <summary>");
-            this.summary.split("\n").forEach((line) => {
-                writer.writeLine(`/// ${line}`);
-            });
-            writer.writeLine("/// </summary>");
+            const docXmlWriter = new DocXmlWriter(writer);
+            docXmlWriter.writeNodeWithEscaping("summary", this.summary);
         }
 
         if (this.annotations.length > 0) {

generators/csharp/codegen/src/ast/Method.ts

@@ -3,6 +3,7 @@ import { Annotation } from "./Annotation";
 import { ClassReference } from "./ClassReference";
 import { CodeBlock } from "./CodeBlock";
 import { AstNode } from "./core/AstNode";
+import { DocXmlWriter } from "./core/DocXmlWriter";
 import { Writer } from "./core/Writer";
 import { Parameter } from "./Parameter";
 import { Type } from "./Type";
@@ -89,24 +90,16 @@ export class Method extends AstNode {
     }
 
     public write(writer: Writer): void {
+        const docXmlWriter = new DocXmlWriter(writer);
         if (this.summary != null) {
-            writer.writeLine("/// <summary>");
-            this.summary.split("\n").forEach((line) => {
-                writer.writeLine(`/// ${line}`);
-            });
-
-            writer.writeLine("/// </summary>");
+            docXmlWriter.writeNodeWithEscaping("summary", this.summary);
         }
         if (this.codeExample != null) {
-            writer.writeLine("/// <example>");
-            writer.writeLine("/// <code>");
-            this.codeExample.split("\n").forEach((line) => {
-                if (line !== "") {
-                    writer.writeLine(`/// ${line}`);
-                }
-            });
-            writer.writeLine("/// </code>");
-            writer.writeLine("/// </example>");
+            docXmlWriter.writeOpenNode("example");
+            docXmlWriter.writeOpenNode("code");
+            docXmlWriter.writeMultilineWithEscaping(this.codeExample);
+            docXmlWriter.writeCloseNode("code");
+            docXmlWriter.writeCloseNode("example");
         }
 
         if (this.annotations.length > 0) {

generators/csharp/codegen/src/ast/core/DocXmlWriter.ts

@@ -0,0 +1,54 @@
+import { Writer } from "..";
+
+export class DocXmlWriter {
+    writer: Writer;
+    constructor(writer: Writer) {
+        this.writer = writer;
+    }
+
+    public writeLine(text?: string): void {
+        this.writer.writeLine(`/// ${text}`);
+    }
+
+    public writePrefix(): this {
+        this.writer.write("/// ");
+        return this;
+    }
+
+    public writeOpenNode(nodeName: string): void {
+        this.writeLine(`<${nodeName}>`);
+    }
+
+    public writeCloseNode(nodeName: string): void {
+        this.writeLine(`</${nodeName}>`);
+    }
+
+    public writeNode(nodeName: string, text: string): void {
+        this.writeOpenNode(nodeName);
+        this.writeMultiline(text);
+        this.writeCloseNode(nodeName);
+    }
+
+    public writeNodeWithEscaping(nodeName: string, text: string): void {
+        this.writeOpenNode(nodeName);
+        this.writeMultilineWithEscaping(text);
+        this.writeCloseNode(nodeName);
+    }
+
+    public writeMultiline(text: string): void {
+        text.trim()
+            .split("\n")
+            .forEach((line) => {
+                this.writeLine(line);
+            });
+    }
+
+    public writeMultilineWithEscaping(text: string): void {
+        text = this.escapeXmlDocContent(text);
+        this.writeMultiline(text);
+    }
+
+    private escapeXmlDocContent(text: string): string {
+        return text.replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+    }
+}

generators/csharp/codegen/src/ast/core/Writer.ts

@@ -3,6 +3,7 @@ import { ClassReference } from "..";
 import { csharp } from "../..";
 import { BaseCsharpCustomConfigSchema } from "../../custom-config";
 import { AstNode } from "./AstNode";
+import { DocXmlWriter } from "./DocXmlWriter";
 
 type Alias = string;
 type Namespace = string;
@@ -100,7 +101,7 @@ export class Writer extends AbstractWriter {
             if (imports.length > 0) {
                 return `${imports}
     #nullable enable
-    
+
     ${this.buffer}`;
             }
         }

generators/csharp/sdk/versions.yml

@@ -1,3 +1,9 @@
+- version: 1.8.4
+  irVersion: 53
+  createdAt: "2024-10-28"
+  changelogEntry:
+    - type: fix
+      summary: Make sure summary and code examples in XML code comments are XML encoded.
 - version: 1.8.3
   createdAt: "2024-10-28"
   changelogEntry:
@@ -13,12 +19,13 @@
   irVersion: 53
 - version: 1.8.1
   irVersion: 53
-  createdAt: "2024-10-08"
+  createdAt: '2024-10-08'
   changelogEntry:
     - type: fix
       summary: |
         Fixes a bug where the `OauthTokenProvider.cs` was incorrectly referencing
         the endpoint method, causing code to fail to compile.
+  irVersion: 53
 - version: 1.8.0
   createdAt: "2024-08-29"
   changelogEntry: