fix(jsii-pacmak): escape documentation in all positions

packages/jsii-calc/lib/documented.ts

@@ -66,3 +66,30 @@ export class Old {
     // Nothing to do
   }
 }
+
+/**
+ * > Don't use this interface
+ * An interface that shouldn't be used, with the annotation in a weird place.
+ */
+export interface DontUseMe {
+  /**
+   * > Don't set this parameter
+   *
+   * A parameter that shouldn't be set, with the annotation in a weird place.
+   */
+  readonly dontSetMe?: string;
+}
+
+/**
+ * > Don't use this class.
+ *
+ * A class that shouldn't be used, with the annotation in a weird place.
+ */
+export class WeirdDocs {
+  /**
+   * > Don't read this property
+   *
+   * A property that shouldn't be read, with the annotation in a weird place.
+   */
+  public dontReadMe?: string;
+}

packages/jsii-calc/test/assembly.jsii

@@ -5066,6 +5066,42 @@
       "name": "DontComplainAboutVariadicAfterOptional",
       "symbolId": "lib/compliance:DontComplainAboutVariadicAfterOptional"
     },
+    "jsii-calc.DontUseMe": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "stability": "stable",
+        "summary": "> Don't use this interface An interface that shouldn't be used, with the annotation in a weird place."
+      },
+      "fqn": "jsii-calc.DontUseMe",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/documented.ts",
+        "line": 74
+      },
+      "name": "DontUseMe",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "A parameter that shouldn't be set, with the annotation in a weird place.",
+            "stability": "stable",
+            "summary": "> Don't set this parameter."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/documented.ts",
+            "line": 80
+          },
+          "name": "dontSetMe",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "lib/documented:DontUseMe"
+    },
     "jsii-calc.DoubleTrouble": {
       "assembly": "jsii-calc",
       "docs": {
@@ -15944,6 +15980,45 @@
       ],
       "symbolId": "lib/compliance:VoidCallback"
     },
+    "jsii-calc.WeirdDocs": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "remarks": "A class that shouldn't be used, with the annotation in a weird place.",
+        "stability": "stable",
+        "summary": "> Don't use this class."
+      },
+      "fqn": "jsii-calc.WeirdDocs",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        }
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/documented.ts",
+        "line": 88
+      },
+      "name": "WeirdDocs",
+      "properties": [
+        {
+          "docs": {
+            "remarks": "A property that shouldn't be read, with the annotation in a weird place.",
+            "stability": "stable",
+            "summary": "> Don't read this property."
+          },
+          "locationInModule": {
+            "filename": "lib/documented.ts",
+            "line": 94
+          },
+          "name": "dontReadMe",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "lib/documented:WeirdDocs"
+    },
     "jsii-calc.WithPrivatePropertyInConstructor": {
       "assembly": "jsii-calc",
       "docs": {
@@ -18843,5 +18918,5 @@
     }
   },
   "version": "3.20.120",
-  "fingerprint": "EH7xszNdCh9PCFUZ8Foi7g2CPhdrKeZm8CQaUCNv4GQ="
+  "fingerprint": "Az+OldqYgxrsbv6RJTr31UU9z51a8MIvn3tY2gQtVKE="
 }

packages/jsii-pacmak/lib/targets/java.ts

@@ -1024,7 +1024,7 @@ class JavaGenerator extends Generator {
     this.code.openFile(packageInfoFile);
     this.code.line('/**');
     if (mod.readme) {
-      for (const line of markDownToJavaDoc(
+      for (const line of myMarkDownToJavaDoc(
         this.convertSamplesInMarkdown(mod.readme.markdown, {
           api: 'moduleReadme',
           moduleFqn: mod.name,
@@ -1058,7 +1058,7 @@ class JavaGenerator extends Generator {
     this.code.openFile(packageInfoFile);
     this.code.line('/**');
     if (mod.readme) {
-      for (const line of markDownToJavaDoc(
+      for (const line of myMarkDownToJavaDoc(
         this.convertSamplesInMarkdown(mod.readme.markdown, {
           api: 'moduleReadme',
           moduleFqn,
@@ -2281,7 +2281,7 @@ class JavaGenerator extends Generator {
       );
       if (prop.docs?.remarks != null) {
         const indent = ' '.repeat(7 + prop.fieldName.length);
-        const remarks = markDownToJavaDoc(
+        const remarks = myMarkDownToJavaDoc(
           this.convertSamplesInMarkdown(prop.docs.remarks, {
             api: 'member',
             fqn: prop.definingType.fqn,
@@ -2710,14 +2710,14 @@ class JavaGenerator extends Generator {
     const paras = [];
 
     if (docs.summary) {
-      paras.push(renderSummary(docs));
+      paras.push(stripNewLines(myMarkDownToJavaDoc(renderSummary(docs))));
     } else if (defaultText) {
-      paras.push(defaultText);
+      paras.push(myMarkDownToJavaDoc(defaultText));
     }
 
     if (docs.remarks) {
       paras.push(
-        markDownToJavaDoc(
+        myMarkDownToJavaDoc(
           this.convertSamplesInMarkdown(docs.remarks, apiLoc),
         ).trimRight(),
       );
@@ -2744,22 +2744,22 @@ class JavaGenerator extends Generator {
       // Hence, we just resort to HTML-encoding everything (same as we do for code
       // examples that have been translated from MarkDown).
       paras.push(
-        markDownToJavaDoc(['```', convertedExample, '```'].join('\n')),
+        myMarkDownToJavaDoc(['```', convertedExample, '```'].join('\n')),
       );
     }
 
     const tagLines = [];
 
     if (docs.returns) {
-      tagLines.push(`@return ${docs.returns}`);
+      tagLines.push(`@return ${myMarkDownToJavaDoc(docs.returns)}`);
     }
     if (docs.see) {
       tagLines.push(
         `@see <a href="${escape(docs.see)}">${escape(docs.see)}</a>`,
       );
     }
     if (docs.deprecated) {
-      tagLines.push(`@deprecated ${docs.deprecated}`);
+      tagLines.push(`@deprecated ${myMarkDownToJavaDoc(docs.deprecated)}`);
     }
 
     // Params
@@ -3462,7 +3462,7 @@ function paramJavadoc(
 ): string {
   const parts = ['@param', name];
   if (summary) {
-    parts.push(endWithPeriod(summary));
+    parts.push(stripNewLines(myMarkDownToJavaDoc(endWithPeriod(summary))));
   }
   if (!optional) {
     parts.push('This parameter is required.');
@@ -3640,3 +3640,19 @@ function containsUnionType(
       containsUnionType(typeRef.collection.elementtype))
   );
 }
+
+function myMarkDownToJavaDoc(source: string) {
+  if (source.includes('{@link') || source.includes('{@code')) {
+    // Slightly dirty hack: if we are seeing this, it means the docstring was provided literally
+    // in this file. These strings are safe to not be escaped, and in fact escaping them will
+    // break them: they will turn into `{&#64;`, which breaks the JavaDoc markup.
+    //
+    // Since docstring do not (or at least should not) contain JavaDoc literals, this is safe.
+    return source;
+  }
+  return markDownToJavaDoc(source);
+}
+
+function stripNewLines(x: string) {
+  return x.replace(/\n/g, '');
+}