fix(pacmak): '*/' not escaped in JavaDocs

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

@@ -2336,10 +2336,22 @@ class JavaGenerator extends Generator {
 
     if (docs.example) {
       paras.push('Example:');
+
+      const convertedExample = this.convertExample(docs.example);
+
+      // We used to use the slightly nicer `<pre>{@code ...}</pre>`, which doesn't
+      // require (and therefore also doesn't allow) escaping special characters.
+      //
+      // However, code samples may contain block quotes of their own ('*/') that
+      // would terminate the block comment from the PoV of the Java tokenizer, and
+      // since `{@code ... }` doesn't allow any escaping, there's also no way to encode
+      // '*/' in a way that would (a) hide it from the tokenizer and (b) give '*/' back
+      // after processing JavaDocs.
+      //
+      // Hence, we just resort to HTML-encoding everything (same as we do for code
+      // examples that have been translated from MarkDown).
       paras.push(
-        `<blockquote><pre>{@code\n${this.convertExample(
-          docs.example,
-        )}}</pre></blockquote>`,
+        markDownToJavaDoc(['```', convertedExample, '```'].join('\n')),
       );
     }
 

packages/jsii-rosetta/lib/markdown/javadoc-renderer.ts

@@ -43,7 +43,7 @@ export class JavaDocRenderer extends MarkdownRenderer {
   }
 
   public document(_node: cm.Node, context: RendererContext) {
-    return stripTrailingWhitespace(collapseParaJava(context.content()));
+    return stripTrailingWhitespace(specialDocCommentEscape(collapseParaJava(context.content())));
   }
 
   public heading(node: cm.Node, context: RendererContext) {
@@ -80,3 +80,18 @@ export class JavaDocRenderer extends MarkdownRenderer {
 function collapseParaJava(x: string) {
   return collapsePara(x, '\n<p>\n');
 }
+
+/**
+ * A final single-pass escape of '* /' which might otherwise end a doc comment.
+ *
+ * We have to do this in one final pass because I've observed that in running
+ * next, the MarkDown parser will parse the two symbols to:
+ *
+ *    [..., text('*'), text('/'), ...]
+ *
+ * which means we have no other ability to observe the two-character combination
+ * properly.
+ */
+function specialDocCommentEscape(x: string) {
+  return x.replace(new RegExp('\\*\\/', 'g'), '*&#47;');
+}

packages/jsii-rosetta/test/markdown/javadoc.test.ts

@@ -91,6 +91,19 @@ if (x < 3) {
   );
 });
 
+test('doc comment closing chars are escaped', () => {
+  expectOutput(
+    ['Escape this */', '```', 'And this */', '```'].join('\n'),
+    `
+Escape this */
+<p>
+<blockquote><pre>
+And this *&#47;
+</pre></blockquote>
+  `,
+  );
+});
+
 test('quotes are escaped inside attributes', () => {
   expectOutput(
     `