Remove unnecessary escaping of /* sequences in JSDoc comments

Co-authored-by: FDiskas <[email protected]>

Author: Copilot

src/schema-parser/schema-formatters.ts

@@ -105,17 +105,16 @@ export class SchemaFormatters {
   escapeJSDocContent = (content) => {
     if (!content) return "";
     // Escape */ sequences to prevent breaking out of JSDoc comments
-    // Escape /* sequences to prevent creating nested comments
+    // Note: /* sequences inside JSDoc comments are harmless and don't need escaping
     return content
-      .replace(/\*\//g, "*\\/")
-      .replace(/\/\*/g, "\\/*");
+      .replace(/\*\//g, "*\\/");
   };
 
   formatDescription = (description, inline) => {
     if (!description) return "";
 
     // Check if content is already escaped - if so, don't escape again
-    const isAlreadyEscaped = description.includes('*\\/') || description.includes('\\/*');
+    const isAlreadyEscaped = description.includes('*\\/');
 
     // Escape JSDoc comment characters only if not already escaped
     const escapedDescription = isAlreadyEscaped ? description : this.escapeJSDocContent(description);

templates/base/route-docs.ejs

@@ -9,7 +9,7 @@ const jsDocDescription = raw.description ?
 const jsDocLines = _.compact([
     _.size(raw.tags) && ` * @tags ${raw.tags.join(", ")}`,
     ` * @name ${pascalCase(routeName.usage)}`,
-    raw.summary && ` * @summary ${escapeJSDocContent(raw.summary)}`,
+    raw.summary && ` * @summary ${formatDescription(raw.summary, true)}`,
     ` * @request ${_.upperCase(request.method)}:${raw.route}`,
     raw.deprecated && ` * @deprecated`,
     routeName.duplicate && ` * @originalName ${routeName.original}`,
@@ -18,7 +18,7 @@ const jsDocLines = _.compact([
     ...(config.generateResponses && raw.responsesTypes.length
     ? raw.responsesTypes.map(
         ({ type, status, description, isSuccess }) =>
-            ` * @response \`${status}\` \`${_.replace(_.replace(type, /\/\*/g, "\\*"), /\*\//g, "*\\")}\` ${escapeJSDocContent(description)}`,
+            ` * @response \`${status}\` \`${_.replace(_.replace(type, /\/\*/g, "\\*"), /\*\//g, "*\\")}\` ${formatDescription(description, true)}`,
         )
     : []),
 ]).map(str => str.trimEnd()).join("\n");

tests/__snapshots__/extended.test.ts.snap

@@ -27686,7 +27686,7 @@ export interface SecretScanningUpdateAlertPayload {
 export interface SelectedActions {
   /** Whether GitHub-owned actions are allowed. For example, this includes the actions in the \`actions\` organization. */
   github_owned_allowed: boolean;
-  /** Specifies a list of string-matching patterns to allow specific action(s). Wildcards, tags, and SHAs are allowed. For example, \`monalisa/octocat@*\`, \`monalisa/octocat@v2\`, \`monalisa\\/*\`." */
+  /** Specifies a list of string-matching patterns to allow specific action(s). Wildcards, tags, and SHAs are allowed. For example, \`monalisa/octocat@*\`, \`monalisa/octocat@v2\`, \`monalisa/*\`." */
   patterns_allowed: string[];
   /** Whether actions in GitHub Marketplace from verified creators are allowed. Set to \`true\` to allow all GitHub Marketplace actions by verified creators. */
   verified_allowed: boolean;

tests/__snapshots__/simple.test.ts.snap

@@ -15493,7 +15493,7 @@ export enum SecretScanningAlertState {
 export interface SelectedActions {
   /** Whether GitHub-owned actions are allowed. For example, this includes the actions in the \`actions\` organization. */
   github_owned_allowed: boolean;
-  /** Specifies a list of string-matching patterns to allow specific action(s). Wildcards, tags, and SHAs are allowed. For example, \`monalisa/octocat@*\`, \`monalisa/octocat@v2\`, \`monalisa\\/*\`." */
+  /** Specifies a list of string-matching patterns to allow specific action(s). Wildcards, tags, and SHAs are allowed. For example, \`monalisa/octocat@*\`, \`monalisa/octocat@v2\`, \`monalisa/*\`." */
   patterns_allowed: string[];
   /** Whether actions in GitHub Marketplace from verified creators are allowed. Set to \`true\` to allow all GitHub Marketplace actions by verified creators. */
   verified_allowed: boolean;

tests/spec/jsdoc-escaping/__snapshots__/basic.test.ts.snap

@@ -13,16 +13,16 @@ exports[`jsdoc-escaping > should escape JSDoc comment characters in descriptions
  * ---------------------------------------------------------------
  */
 
-/** Information schema with malicious **\\/ window.location='http://evil.com' \\/** content */
+/** Information schema with malicious **\\/ window.location='http://evil.com' /** content */
 export interface Information {
-  /** The ID of the information record. Contains **\\/ dangerous content \\/** here. */
+  /** The ID of the information record. Contains **\\/ dangerous content /** here. */
   id?: number;
-  /** Title field with *\\/ and \\/* characters that could break comments */
+  /** Title field with *\\/ and /* characters that could break comments */
   title?: string;
   /**
    * Multi-line description
    * with *\\/ characters
-   * and \\/* other markers
+   * and /* other markers
    * that could break JSDoc comments
    */
   content?: string;
@@ -291,7 +291,7 @@ export class Api<
      * @description Get service point file of all Nordic countries (SE,FI,DK,NO) from S3 storage. You can download previous service point file upto 7 days from current date. This is equivalent to **\\/information** endpoint with parameters \`countryCode:SE,FI,DK,NO\` and \`context:ALL\` and header \`Accept-Encoding:gzip\`.
      *
      * @name InformationList
-     * @summary Get service point file with **\\/ alert('XSS') \\/** injection attempt
+     * @summary Get service point file with **\\/ alert('XSS') /** injection attempt
      * @request GET:/information
      */
     informationList: (params: RequestParams = {}) =>

tests/spec/jsdoc-escaping/basic.test.ts

@@ -32,9 +32,9 @@ describe("jsdoc-escaping", async () => {
     expect(content).not.toMatch(/\*\/ window\./); // No unescaped window manipulation
     expect(content).not.toMatch(/\*\/ dangerous content \*\//); // No unescaped dangerous content
 
-    // Check that escaping is applied - look for backslash escapes
+    // Check that only necessary escaping is applied
     expect(content).toMatch(/\*\\\//); // Should contain escaped */ 
-    expect(content).toMatch(/\\\//); // Should contain escaped /*
+    expect(content).not.toMatch(/\\\*\//); // Should NOT contain escaped /* sequences
 
     // Check that alert and window are escaped
     expect(content).toMatch(/alert\('XSS'\)/); // Should still contain the content but safely escaped