feat(rosetta): add skeleton of Java snippet translator

packages/@scope/jsii-calc-lib/test/assembly.jsii

@@ -121,8 +121,9 @@
     "@scope/jsii-calc-lib.EnumFromScopedModule": {
       "assembly": "@scope/jsii-calc-lib",
       "docs": {
+        "remarks": "See awslabs/jsii#138",
         "stability": "deprecated",
-        "summary": "Check that enums from \\@scoped packages can be references. See awslabs/jsii#138."
+        "summary": "Check that enums from \\@scoped packages can be references."
       },
       "fqn": "@scope/jsii-calc-lib.EnumFromScopedModule",
       "kind": "enum",
@@ -539,5 +540,5 @@
     }
   },
   "version": "0.20.8",
-  "fingerprint": "FFFRcCrdPYvpu+IupXHGE0msGdLt4fpbgDMBKjGdCOs="
+  "fingerprint": "dP9qhYQ8sdUC+F7c427cCKa0pFPvot6EAZn2BNeUlNM="
 }

packages/jsii-calc/test/assembly.jsii

@@ -7194,9 +7194,9 @@
           "abstract": true,
           "docs": {
             "default": "256",
-            "remarks": "This default is set in the underlying FargateTaskDefinition construct.",
+            "remarks": "Valid values, which determines your range of valid values for the memory parameter:\n256 (.25 vCPU) - Available memory values: 0.5GB, 1GB, 2GB\n512 (.5 vCPU) - Available memory values: 1GB, 2GB, 3GB, 4GB\n1024 (1 vCPU) - Available memory values: 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB\n2048 (2 vCPU) - Available memory values: Between 4GB and 16GB in 1GB increments\n4096 (4 vCPU) - Available memory values: Between 8GB and 30GB in 1GB increments\n\nThis default is set in the underlying FargateTaskDefinition construct.",
             "stability": "experimental",
-            "summary": "The number of cpu units used by the task. Valid values, which determines your range of valid values for the memory parameter: 256 (.25 vCPU) - Available memory values: 0.5GB, 1GB, 2GB 512 (.5 vCPU) - Available memory values: 1GB, 2GB, 3GB, 4GB 1024 (1 vCPU) - Available memory values: 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB 2048 (2 vCPU) - Available memory values: Between 4GB and 16GB in 1GB increments 4096 (4 vCPU) - Available memory values: Between 8GB and 30GB in 1GB increments."
+            "summary": "The number of cpu units used by the task."
           },
           "immutable": true,
           "locationInModule": {
@@ -8536,8 +8536,9 @@
         },
         {
           "docs": {
+            "remarks": "Must be implemented by derived classes.",
             "stability": "experimental",
-            "summary": "The expression that this operation consists of. Must be implemented by derived classes."
+            "summary": "The expression that this operation consists of."
           },
           "immutable": true,
           "locationInModule": {
@@ -9811,8 +9812,9 @@
         },
         {
           "docs": {
+            "remarks": "Jsdocs for static setter.",
             "stability": "experimental",
-            "summary": "Jsdocs for static getter. Jsdocs for static setter."
+            "summary": "Jsdocs for static getter."
           },
           "locationInModule": {
             "filename": "lib/compliance.ts",
@@ -10305,8 +10307,9 @@
       "properties": [
         {
           "docs": {
+            "remarks": "Must be implemented by derived classes.",
             "stability": "experimental",
-            "summary": "The expression that this operation consists of. Must be implemented by derived classes."
+            "summary": "The expression that this operation consists of."
           },
           "immutable": true,
           "locationInModule": {
@@ -11627,8 +11630,9 @@
         {
           "abstract": true,
           "docs": {
+            "remarks": "Must be implemented by derived classes.",
             "stability": "experimental",
-            "summary": "The expression that this operation consists of. Must be implemented by derived classes."
+            "summary": "The expression that this operation consists of."
           },
           "immutable": true,
           "locationInModule": {
@@ -11743,5 +11747,5 @@
     }
   },
   "version": "0.20.8",
-  "fingerprint": "w4S74J2aEQiII5p1/vLG5rXFrtvbxUP1mra7ZGBd4so="
+  "fingerprint": "RXyKxe7cZhjQraeBtWqnjdNPkV1KRAT6oHLGnU2sla4="
 }

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

@@ -239,7 +239,7 @@ export default class Dotnet extends Target {
   public constructor(options: TargetOptions, assembliesCurrentlyBeingCompiled: string[]) {
     super(options);
 
-    this.generator = new DotNetGenerator(assembliesCurrentlyBeingCompiled);
+    this.generator = new DotNetGenerator(assembliesCurrentlyBeingCompiled, options.rosetta);
   }
 
   /* eslint-disable @typescript-eslint/require-await */

packages/jsii-pacmak/lib/targets/dotnet/dotnetdocgenerator.ts

@@ -1,11 +1,10 @@
 import { CodeMaker } from 'codemaker';
 import * as spec from '@jsii/spec';
 import { DotNetNameUtils } from './nameutils';
-import { prefixMarkdownTsCodeBlocks } from '../../util';
+import { Rosetta, Translation, typeScriptSnippetFromSource, markDownToXmlDoc } from 'jsii-rosetta';
+import { INCOMPLETE_DISCLAIMER_COMPILING, INCOMPLETE_DISCLAIMER_NONCOMPILING } from '..';
 
 
-const SAMPLES_DISCLAIMER = '// This example is in TypeScript, examples in C# are coming soon.';
-
 /**
  * Generates the Jsii attributes and calls for the .NET runtime
  *
@@ -15,7 +14,7 @@ export class DotNetDocGenerator {
   private readonly code: CodeMaker;
   private readonly nameutils: DotNetNameUtils = new DotNetNameUtils();
 
-  public constructor(code: CodeMaker) {
+  public constructor(code: CodeMaker, private readonly rosetta: Rosetta) {
     this.code = code;
   }
 
@@ -29,7 +28,7 @@ export class DotNetDocGenerator {
      * Returns
      * Remarks (includes examples, links, deprecated)
      */
-  public emitDocs(obj: spec.Method | spec.InterfaceType | spec.ClassType | spec.Property | spec.EnumType | spec.Initializer): void {
+  public emitDocs(obj: spec.Documentable): void {
     const docs = obj.docs;
 
     // The docs may be undefined at the method level but not the parameters level
@@ -52,7 +51,7 @@ export class DotNetDocGenerator {
       });
     }
 
-    // At this point we only need a valid instance of docs
+    // At this pdocfx namespacedocd a valid instance of docs
     if (!docs) {
       return;
     }
@@ -64,62 +63,101 @@ export class DotNetDocGenerator {
       this.code.line('/// </returns>');
     }
 
-    const remarks: string[] = [];
-    let remarksOpen = false;
-    if (docs.remarks) {
+    const remarks = this.renderRemarks(docs);
+    if (remarks.length > 0) {
       this.code.line('/// <remarks>');
-      remarksOpen = true;
-      const remarkLines = prefixMarkdownTsCodeBlocks(docs.remarks, SAMPLES_DISCLAIMER).split('\n');
-      remarkLines.forEach( line => this.code.line(`/// ${line}`));
+      remarks.forEach(r => this.code.line(`/// ${r}`));
+      this.code.line('/// </remarks>');
     }
 
-    if (docs.default) {
-      const defaultLines = docs.default.split('\n');
-      remarks.push('default:');
-      defaultLines.forEach( line => remarks.push(`${line}`));
+    if (docs.example) {
+      const exampleLines = this.convertExample(docs.example).split('\n');
+      this.code.line('/// <example>');
+      this.code.line('/// <code>');
+      exampleLines.forEach( line => this.code.line(`/// ${line}`));
+      this.code.line('/// </code>');
+      this.code.line('/// </example>');
     }
+  }
 
-    if (docs.stability) {
-      remarks.push(`stability: ${this.nameutils.capitalizeWord(docs.stability)}`);
-    }
+  public emitMarkdownAsRemarks(markdown: string | undefined) {
+    if (!markdown) { return; }
 
-    if (docs.example) {
-      const remarkLines = docs.example.split('\n');
-      remarks.push('example:');
-      remarks.push('<code>');
-      remarks.push('// Examples in C# are coming soon.');
-      remarkLines.forEach( line => remarks.push(`${line}`));
-      remarks.push('</code>');
-    }
+    const translated = markDownToXmlDoc(this.convertSamplesInMarkdown(markdown));
+    const lines = translated.split('\n');
 
-    if (docs.see) {
-      const seeLines = docs.see.split('\n');
-      remarks.push('see:');
-      seeLines.forEach( line => remarks.push(`${line}`));
+    this.code.line('/// <remarks>');
+    for (const line of lines) {
+      this.code.line(`/// ${line}`);
     }
+    this.code.line('/// </remarks>');
+  }
+
+  /**
+   * Returns the lines that should go into the <remarks> section
+   */
+  private renderRemarks(docs: spec.Docs): string[] {
+    const ret: string[] = [];
 
-    if (docs.subclassable) {
-      remarks.push('subclassable');
+    if (docs.remarks) {
+      const translated = markDownToXmlDoc(this.convertSamplesInMarkdown(docs.remarks));
+      ret.push(...translated.split('\n'));
+      ret.push('');
     }
 
-    if (docs.custom) {
-      for (const [k, v] of Object.entries(docs.custom ?? {})) {
-        const custom = k === 'link' ? `${k}: ${v} ` : `${k}: ${v}`; // Extra space for '@link' to keep unit tests happy
-        const customLines = custom.split('\n');
-        customLines.forEach( line => remarks.push(`${line}`));
-      }
+    // All the "tags" need to be rendered with empyt lines between them or they'll be word wrapped.
+
+    if (docs.default) { emitDocAttribute('default', docs.default); }
+    if (docs.stability) { emitDocAttribute('stability', this.nameutils.capitalizeWord(docs.stability)); }
+    if (docs.see) { emitDocAttribute('see', docs.see); }
+    if (docs.subclassable) { emitDocAttribute('subclassable', ''); }
+    for (const [k, v] of Object.entries(docs.custom || {})) {
+      const extraSpace = k === 'link' ? ' ' : ''; // Extra space for '@link' to keep unit tests happy
+      emitDocAttribute(k, v + extraSpace);
     }
 
-    if (remarks.length > 0) {
-      if (!remarksOpen) {
-        this.code.line('/// <remarks>');
-        remarksOpen = true;
-      }
-      remarks.forEach( line => this.code.line(`/// ${line}`));
+    // Remove leading and trailing empty lines
+    while (ret.length > 0 && ret[0] === '') { ret.shift(); }
+    while (ret.length > 0 && ret[ret.length - 1] === '') { ret.pop(); }
+
+    return ret;
+
+    function emitDocAttribute(name: string, contents: string) {
+      const ls = contents.split('\n');
+      ret.push(`<strong>${ucFirst(name)}</strong>: ${ls[0]}`);
+      ret.push(...ls.slice(1));
+      ret.push('');
     }
+  }
 
-    if (remarksOpen) {
-      this.code.line('/// </remarks>');
+  private convertExample(example: string): string {
+    const snippet = typeScriptSnippetFromSource(example, 'example');
+    const translated = this.rosetta.translateSnippet(snippet, 'csharp');
+    if (!translated) { return example; }
+    return this.prefixDisclaimer(translated);
+  }
+
+  private convertSamplesInMarkdown(markdown: string): string {
+    return this.rosetta.translateSnippetsInMarkdown(markdown, 'csharp', trans => ({
+      language: trans.language,
+      source: this.prefixDisclaimer(trans)
+    }));
+  }
+
+  private prefixDisclaimer(translated: Translation) {
+    if (translated.didCompile && INCOMPLETE_DISCLAIMER_COMPILING) {
+      return `// ${INCOMPLETE_DISCLAIMER_COMPILING}\n${translated.source}`;
     }
+    if (!translated.didCompile && INCOMPLETE_DISCLAIMER_NONCOMPILING) {
+      return `// ${INCOMPLETE_DISCLAIMER_NONCOMPILING}\n${translated.source}`;
+    }
+    return translated.source;
   }
 }
+
+/**
+ * Uppercase the first letter
+ */
+function ucFirst(x: string) {
+  return x.substr(0, 1).toUpperCase() + x.substr(1);
+}

packages/jsii-pacmak/lib/targets/dotnet/dotnetgenerator.ts

@@ -9,6 +9,7 @@ import { DotNetRuntimeGenerator } from './dotnetruntimegenerator';
 import { DotNetTypeResolver } from './dotnettyperesolver';
 import { DotNetDependency, FileGenerator } from './filegenerator';
 import { DotNetNameUtils } from './nameutils';
+import { Rosetta } from 'jsii-rosetta';
 
 /**
  * CODE GENERATOR V2
@@ -28,7 +29,7 @@ export class DotNetGenerator extends Generator {
 
   private dotnetDocGenerator!: DotNetDocGenerator;
 
-  public constructor(private readonly assembliesCurrentlyBeingCompiled: string[]) {
+  public constructor(private readonly assembliesCurrentlyBeingCompiled: string[], private readonly rosetta: Rosetta) {
     super();
 
     // Override the openBlock to get a correct C# looking code block with the curly brace after the line
@@ -54,7 +55,9 @@ export class DotNetGenerator extends Generator {
     );
 
     this.dotnetRuntimeGenerator = new DotNetRuntimeGenerator(this.code, this.typeresolver);
-    this.dotnetDocGenerator = new DotNetDocGenerator(this.code);
+    this.dotnetDocGenerator = new DotNetDocGenerator(this.code, this.rosetta);
+
+    this.emitNamespaceDocs();
 
     // We need to resolve the dependency tree
     this.typeresolver.resolveNamespacesDependencies();
@@ -270,11 +273,13 @@ export class DotNetGenerator extends Generator {
     }
 
     this.dotnetRuntimeGenerator.emitDeprecatedAttributeIfNecessary(initializer);
+    this.emitHideAttribute();
     this.code.openBlock(`protected ${className}(ByRefValue reference): base(reference)`);
     this.code.closeBlock();
     this.code.line();
 
     this.dotnetRuntimeGenerator.emitDeprecatedAttributeIfNecessary(initializer);
+    this.emitHideAttribute();
     this.code.openBlock(`protected ${className}(DeputyProps props): base(props)`);
     this.code.closeBlock();
 
@@ -795,4 +800,40 @@ export class DotNetGenerator extends Generator {
       this.firstMemberWritten = false;
     }
   }
+
+  /**
+   * Emit an unused, empty class called `NamespaceDoc` to attach the module README to
+   *
+   * There is no way to attach doc comments to a namespace in C#, and this trick has been
+   * semi-standardized by NDoc and Sandcastle Help File Builder.
+   *
+   * DocFX doesn't support it out of the box, but we should be able to get there with a
+   * bit of hackery.
+   *
+   * In any case, we need a place to attach the docs where they can be transported around,
+   * might as well be this method.
+   */
+  private emitNamespaceDocs() {
+    if (!this.assembly.readme) { return; }
+
+    const namespace = this.assembly.targets!.dotnet!.namespace;
+    const className = 'NamespaceDoc';
+    this.openFileIfNeeded(className, namespace, false, false);
+
+    this.dotnetDocGenerator.emitMarkdownAsRemarks(this.assembly.readme.markdown);
+    this.emitHideAttribute();
+    // Traditionally this class is made 'internal', but that interacts poorly with DocFX's default filters
+    // which aren't overridable. So we make it public, but use attributes to hide it from users' IntelliSense,
+    // so that we can access the class in DocFX.
+    this.code.openBlock(`public class ${className}`);
+    this.code.closeBlock();
+    this.closeFileIfNeeded(className, namespace, false);
+  }
+
+  /**
+   * Emit an attribute that will hide the subsequent API element from users
+   */
+  private emitHideAttribute() {
+    this.code.line('[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]');
+  }
 }

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

@@ -19,4 +19,5 @@ export const ALL_BUILDERS: {[key in TargetName]: BuilderFactory} = {
   ruby: (ms, o) => new OneByOneBuilder('ruby', Ruby, ms, o),
 };
 
-
+export const INCOMPLETE_DISCLAIMER_COMPILING = 'Example automatically generated. See https://github.com/aws/jsii/issues/826';
+export const INCOMPLETE_DISCLAIMER_NONCOMPILING = 'Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826';