Support for comments

Author: engthiago

README.md

@@ -85,6 +85,12 @@ Controls semicolons on generated TypeScript statements. Options: `true`, `false`
 `--normalize-acronyms`, `--no-normalize-acronyms` optional  
 Normalizes leading acronyms in generated property names, such as `ULS` to `uls`. Default: `false`.
 
+`--preserve-comments`, `--no-preserve-comments` optional  
+Emits parsed C# comments in generated TypeScript files. Default: `false`.
+
+`--convert-documentation-comments`, `--no-convert-documentation-comments` optional  
+Converts C# XML documentation comments (`///`) into TypeScript JSDoc comments. Default: `false`.
+
 ## Configuration File
 
 Create `typesharp.json`:
@@ -102,7 +108,9 @@ Create `typesharp.json`:
   "readonlyProperties": false,
   "quoteStyle": "double",
   "semicolons": true,
-  "normalizeAcronyms": false
+  "normalizeAcronyms": false,
+  "preserveComments": false,
+  "convertDocumentationComments": false
 }
 ```
 

src/typesharp-ts/dist/main.mjs

@@ -149,6 +149,68 @@ public class Report {
   assert.match(normalizedReport, /urlValue: string;/);
 });
 
+test("preserves comments only when enabled", () => {
+  const files = [
+    parseSourceFile(
+      "commented.cs",
+      `
+/// <summary>Report docs</summary>
+public class Report {
+  // Property docs
+  public string Name { get; set; } // trailing docs
+  /// <summary>Count docs</summary>
+  /* block docs */
+  public int Count { get; set; }
+}
+
+/// <summary>Status docs</summary>
+public enum Status {
+  // Invalid docs
+  Invalid = -1,
+  /// <summary>Valid docs</summary>
+  Valid = 1,
+}
+`,
+    ),
+  ];
+
+  const defaultGenerated = new Map(generate(files).map((file) => [file.name, file.text]));
+  assert.doesNotMatch(defaultGenerated.get("Report.ts")!, /Report docs|Property docs|trailing docs|block docs|Count docs/);
+  assert.doesNotMatch(defaultGenerated.get("Status.ts")!, /Status docs|Invalid docs|Valid docs/);
+
+  const preserved = new Map(generate(files, { preserveComments: true }).map((file) => [file.name, file.text]));
+  assert.match(preserved.get("Report.ts")!, /\/\/\/ <summary>Report docs<\/summary>\nexport interface Report/);
+  assert.match(preserved.get("Report.ts")!, /   \/\/ Property docs\n   name: string; \/\/ trailing docs/);
+  assert.match(preserved.get("Report.ts")!, /   \/\/\/ <summary>Count docs<\/summary>\n   \/\* block docs \*\/\n   count: number;/);
+  assert.match(preserved.get("Status.ts")!, /\/\/\/ <summary>Status docs<\/summary>\nexport enum Status/);
+  assert.match(preserved.get("Status.ts")!, /   \/\/ Invalid docs\n   Invalid = -1,/);
+  assert.match(preserved.get("Status.ts")!, /   \/\/\/ <summary>Valid docs<\/summary>\n   Valid = 1,/);
+});
+
+test("converts documentation comments without preserving ordinary comments", () => {
+  const files = [
+    parseSourceFile(
+      "commented.cs",
+      `
+/// <summary>Report docs</summary>
+/// <remarks>More details</remarks>
+public class Report {
+  // Ordinary comment
+  /// <summary>Name docs</summary>
+  public string Name { get; set; } // trailing docs
+}
+`,
+    ),
+  ];
+
+  const generated = new Map(
+    generate(files, { convertDocumentationComments: true }).map((file) => [file.name, file.text]),
+  ).get("Report.ts")!;
+  assert.match(generated, /\/\*\*\n \* Report docs\n \*\n \* More details\n \*\/\nexport interface Report/);
+  assert.match(generated, /   \/\*\*\n    \* Name docs\n    \*\/\n   name: string;/);
+  assert.doesNotMatch(generated, /Ordinary comment|trailing docs|\/\/\//);
+});
+
 test("supports property readonly attributes without global readonly", () => {
   const person = generate([
     parseSourceFile(
@@ -253,6 +315,8 @@ test("supports current CLI arguments", () => {
       "--quote-style=single",
       "--no-semicolons",
       "--normalize-acronyms",
+      "--preserve-comments",
+      "--convert-documentation-comments",
     ]),
     {
       configPath: "./config/tssharp.json",
@@ -268,6 +332,8 @@ test("supports current CLI arguments", () => {
       quoteStyle: "single",
       semicolons: false,
       normalizeAcronyms: true,
+      preserveComments: true,
+      convertDocumentationComments: true,
     },
   );
 });
@@ -286,6 +352,8 @@ test("loads typesharp.json and lets CLI override file values", async () => {
         dictionaryStyle: "index-signature",
         readonlyProperties: true,
         normalizeAcronyms: true,
+        preserveComments: true,
+        convertDocumentationComments: true,
       }),
     );
 
@@ -303,6 +371,8 @@ test("loads typesharp.json and lets CLI override file values", async () => {
       quoteStyle: undefined,
       semicolons: undefined,
       normalizeAcronyms: true,
+      preserveComments: true,
+      convertDocumentationComments: true,
     });
   } finally {
     await rm(temp, { recursive: true, force: true });
@@ -334,6 +404,8 @@ test("defaults fileFilter to C# source files", async () => {
       quoteStyle: undefined,
       semicolons: undefined,
       normalizeAcronyms: undefined,
+      preserveComments: undefined,
+      convertDocumentationComments: undefined,
     });
   } finally {
     await rm(temp, { recursive: true, force: true });

src/typesharp-ts/spec/node_test.ts

@@ -1,4 +1,4 @@
-import { AttributeNode, ClassNode, SourceFileNode, TypeDeclarationNode, TypeReferenceNode } from "./ast";
+import { AttributeNode, ClassNode, CommentTrivia, SourceFileNode, TypeDeclarationNode, TypeReferenceNode } from "./ast";
 
 export interface GenerateOptions {
   exportModule?: boolean;
@@ -8,6 +8,8 @@ export interface GenerateOptions {
   quoteStyle?: "double" | "single";
   semicolons?: boolean;
   normalizeAcronyms?: boolean;
+  preserveComments?: boolean;
+  convertDocumentationComments?: boolean;
 }
 
 export interface GeneratedFile {
@@ -41,7 +43,7 @@ export function generate(files: SourceFileNode[], options: GenerateOptions = {})
   const typeMap: TypeMap = { declarations: new Map(declarations.map((d) => [d.name, d])) };
   const output = declarations.map((declaration) => ({
     name: `${declaration.name}.ts`,
-    text: declaration.kind === "enum" ? generateEnum(declaration) : generateClass(declaration, typeMap, settings),
+    text: declaration.kind === "enum" ? generateEnum(declaration, settings) : generateClass(declaration, typeMap, settings),
   }));
 
   if (settings.exportModule) {
@@ -62,10 +64,13 @@ function shouldEmit(declaration: TypeDeclarationNode): boolean {
   return !declaration.name.endsWith("Attribute") && declaration.properties.length > 0;
 }
 
-function generateEnum(node: Extract<TypeDeclarationNode, { kind: "enum" }>): string {
-  const lines = ["", `export enum ${node.name} {`];
+function generateEnum(node: Extract<TypeDeclarationNode, { kind: "enum" }>, options: Required<GenerateOptions>): string {
+  const lines = [""];
+  pushComments(lines, node.leadingComments, "", options);
+  lines.push(`export enum ${node.name} {`);
   for (const member of node.members) {
-    lines.push(`   ${member.name} = ${member.value ?? 0},`);
+    pushComments(lines, member.leadingComments, "   ", options);
+    lines.push(`   ${member.name} = ${member.value ?? 0},${trailingComment(member.trailingComments, options)}`);
   }
   lines.push("}", "");
   return lines.join("\n");
@@ -85,14 +90,20 @@ function generateClass(node: ClassNode, typeMap: TypeMap, options: Required<Gene
     : "";
   const readonlyClass = options.readonlyProperties || hasAttribute(node.attributes, "Readonly") ||
     hasAttribute(node.attributes, "ReadOnly") || hasAttribute(node.attributes, "ReadonlyProperties");
+  pushComments(lines, node.leadingComments, "", options);
   lines.push(`export interface ${node.name}${typeParams}${base} {`);
   for (const prop of node.properties) {
+    pushComments(lines, prop.leadingComments, "   ", options);
     const union = typeUnion(prop.attributes, options);
     const readonly = readonlyClass || hasAttribute(prop.attributes, "Readonly") ||
       hasAttribute(prop.attributes, "ReadOnly");
     const prefix = readonly ? "readonly " : "";
     if (union) {
-      lines.push(`   ${prefix}${propertyName(prop.name, options)}: ${union}${statementEnd(options)}`);
+      lines.push(
+        `   ${prefix}${propertyName(prop.name, options)}: ${union}${statementEnd(options)}${
+          trailingComment(prop.trailingComments, options)
+        }`,
+      );
       continue;
     }
 
@@ -105,13 +116,86 @@ function generateClass(node: ClassNode, typeMap: TypeMap, options: Required<Gene
     lines.push(
       `   ${prefix}${propertyName(prop.name, options)}${optional ? "?" : ""}: ${typeName}${nullable}${
         statementEnd(options)
-      }`,
+      }${trailingComment(prop.trailingComments, options)}`,
     );
   }
   lines.push("}", "");
   return lines.join("\n");
 }
 
+function pushComments(
+  lines: string[],
+  comments: CommentTrivia[],
+  indent: string,
+  options: Required<GenerateOptions>,
+): void {
+  let docComments: CommentTrivia[] = [];
+  const flushDocComments = () => {
+    if (docComments.length === 0) return;
+    if (options.convertDocumentationComments) {
+      pushDocumentationComment(lines, docComments, indent);
+    } else if (options.preserveComments) {
+      for (const comment of docComments) lines.push(`${indent}${comment.text.trim()}`);
+    }
+    docComments = [];
+  };
+
+  for (const comment of comments) {
+    if (comment.kind === "doc") {
+      docComments.push(comment);
+      continue;
+    }
+
+    flushDocComments();
+    if (comment.kind !== "doc" && !options.preserveComments) continue;
+    const text = comment.text.trim();
+    if (comment.kind === "block") {
+      for (const line of text.split(/\r?\n/)) lines.push(`${indent}${line}`);
+    } else {
+      lines.push(`${indent}${text}`);
+    }
+  }
+  flushDocComments();
+}
+
+function trailingComment(comments: CommentTrivia[], options: Required<GenerateOptions>): string {
+  if (!options.preserveComments || comments.length === 0) return "";
+  return ` ${comments.map((comment) => comment.text.trim()).join(" ")}`;
+}
+
+function pushDocumentationComment(lines: string[], comments: CommentTrivia[], indent: string): void {
+  const text = comments
+    .map((comment) => documentationText(comment.text))
+    .join("\n\n")
+    .trim();
+  if (!text) return;
+
+  lines.push(`${indent}/**`);
+  for (const line of text.split(/\r?\n/)) {
+    lines.push(line ? `${indent} * ${line}` : `${indent} *`);
+  }
+  lines.push(`${indent} */`);
+}
+
+function documentationText(text: string): string {
+  const xml = text
+    .split(/\r?\n/)
+    .map((line) => line.trim().replace(/^\/\/\/\s?/, ""))
+    .join("\n")
+    .trim();
+  return xml
+    .replace(/<summary>\s*([\s\S]*?)\s*<\/summary>/gi, "$1")
+    .replace(/<remarks>\s*([\s\S]*?)\s*<\/remarks>/gi, "\n\n$1")
+    .replace(/<returns>\s*([\s\S]*?)\s*<\/returns>/gi, "\n\n@returns $1")
+    .replace(/<param\s+name="([^"]+)">\s*([\s\S]*?)\s*<\/param>/gi, "\n\n@param $1 $2")
+    .replace(/<[^>]+>/g, "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
 function collectImports(node: ClassNode, typeMap: TypeMap): string[] {
   const imports = new Set<string>();
   const visit = (type: TypeReferenceNode) => {
@@ -220,6 +304,8 @@ function normalizeOptions(options: GenerateOptions): Required<GenerateOptions> {
     quoteStyle: options.quoteStyle ?? "double",
     semicolons: options.semicolons ?? true,
     normalizeAcronyms: options.normalizeAcronyms ?? false,
+    preserveComments: options.preserveComments ?? false,
+    convertDocumentationComments: options.convertDocumentationComments ?? false,
   };
 }
 

src/typesharp-ts/src/generator.ts

@@ -51,6 +51,8 @@ export async function convert(options: CliOptions): Promise<void> {
     quoteStyle: options.quoteStyle,
     semicolons: options.semicolons,
     normalizeAcronyms: options.normalizeAcronyms,
+    preserveComments: options.preserveComments,
+    convertDocumentationComments: options.convertDocumentationComments,
   });
   await mkdir(options.destination, { recursive: true });
   for (const file of files) {
@@ -89,6 +91,8 @@ export function parseArgs(args: string[]): ParsedCliOptions {
     "readonly-properties",
     "semicolons",
     "normalize-acronyms",
+    "preserve-comments",
+    "convert-documentation-comments",
   ]);
   const arrayFlags = new Set(["exclude-pattern", "exclude-patterns"]);
 
@@ -165,6 +169,8 @@ function finalizeOptions(options: ConfigFileOptions): CliOptions {
     quoteStyle: options.quoteStyle,
     semicolons: options.semicolons,
     normalizeAcronyms: options.normalizeAcronyms,
+    preserveComments: options.preserveComments,
+    convertDocumentationComments: options.convertDocumentationComments,
   };
 }
 
@@ -183,6 +189,8 @@ function mapRawOptions(values: Map<string, string | boolean>): ParsedCliOptions
   setString(options, "quoteStyle", values.get("quote-style"));
   setBoolean(options, "semicolons", values.get("semicolons"));
   setBoolean(options, "normalizeAcronyms", values.get("normalize-acronyms"));
+  setBoolean(options, "preserveComments", values.get("preserve-comments"));
+  setBoolean(options, "convertDocumentationComments", values.get("convert-documentation-comments"));
   return options;
 }
 

src/typesharp-ts/src/main.ts

@@ -10,5 +10,7 @@
   "readonlyProperties": false,
   "quoteStyle": "double",
   "semicolons": true,
-  "normalizeAcronyms": false
+  "normalizeAcronyms": false,
+  "preserveComments": false,
+  "convertDocumentationComments": false
 }