From 9bb84224e1447f187858426ffb097f4fa71f05fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Mon, 3 Jun 2019 18:40:16 +0200
Subject: [PATCH 1/9] feat: Register module-level stability

Adds the necessary code to detect and forward module-level stability
indications to the assembly, so it can be used by downstream languages.
This effectively removes the `markdown` attribute from the `Assembly` in
favor of using the `docs` attribute.

If a stability indication, a specific badge _must_ be present in the
accompanying `README.md` file (which as a consequence is required to
exist), to denote the maturity of the module in user-visible
documentation, too. The tool prescribes what the badge must look like.

Also, renders a `package-info.json` file for packages that have
documentation (a `README.md` file, deprecation notice, or stability
indication).
---
 packages/jsii-calc/README.md                  |  1 +
 packages/jsii-calc/package.json               |  1 +
 packages/jsii-calc/test/assembly.jsii         | 10 ++--
 packages/jsii-pacmak/lib/markdown.ts          |  8 ++-
 packages/jsii-pacmak/lib/targets/java.ts      | 43 ++++++++++++++-
 packages/jsii-pacmak/lib/targets/python.ts    |  7 ++-
 packages/jsii-pacmak/lib/targets/sphinx.ts    |  4 +-
 .../test/expected.jsii-calc-base/java/pom.xml |  3 ++
 .../test/expected.jsii-calc-lib/java/pom.xml  |  3 ++
 .../.jsii                                     | 10 ++--
 .../test/expected.jsii-calc/java/pom.xml      |  3 ++
 .../jsii/tests/calculator/package-info.java   | 14 +++++
 .../test/expected.jsii-calc/python/README.md  |  1 +
 .../sphinx/_jsii-calc.README.md               |  1 +
 packages/jsii-spec/lib/spec.ts                |  7 ---
 packages/jsii/lib/assembler.ts                | 54 +++++++++++++++----
 packages/jsii/lib/project-info.ts             | 11 ++++
 17 files changed, 150 insertions(+), 31 deletions(-)
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java

diff --git a/packages/jsii-calc/README.md b/packages/jsii-calc/README.md
index 186faff39d..01b164825b 100644
--- a/packages/jsii-calc/README.md
+++ b/packages/jsii-calc/README.md
@@ -1,4 +1,5 @@
 # jsii Calculator
+![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 
diff --git a/packages/jsii-calc/package.json b/packages/jsii-calc/package.json
index 7198cb954b..365d7cdd02 100644
--- a/packages/jsii-calc/package.json
+++ b/packages/jsii-calc/package.json
@@ -5,6 +5,7 @@
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "private": true,
+  "stability": "experimental",
   "jsii": {
     "outdir": "dist",
     "targets": {
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
index 7d7acac404..a78e44d478 100644
--- a/packages/jsii-calc/test/assembly.jsii
+++ b/packages/jsii-calc/test/assembly.jsii
@@ -182,6 +182,11 @@
     }
   },
   "description": "A simple calcuator built on JSII.",
+  "docs": {
+    "remarks": "![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n",
+    "stability": "experimental",
+    "summary": "# jsii Calculator"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -193,9 +198,6 @@
     }
   },
   "name": "jsii-calc",
-  "readme": {
-    "markdown": "# jsii Calculator\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n"
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
@@ -6810,5 +6812,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "i8GdLx7YlhttP5/pB0dKItig1wFkp/DwDdUtbYsIdfc="
+  "fingerprint": "5ejpZLVHjfmn1dghKkB/85hdGJuSRGZtxSIH+SF+b6Y="
 }
diff --git a/packages/jsii-pacmak/lib/markdown.ts b/packages/jsii-pacmak/lib/markdown.ts
index 5ef9017bae..b74866139c 100644
--- a/packages/jsii-pacmak/lib/markdown.ts
+++ b/packages/jsii-pacmak/lib/markdown.ts
@@ -114,6 +114,12 @@ export function md2rst(text: string) {
     return doc.toString();
 }
 
+export function md2html(text: string): string {
+  const parser = new commonmark.Parser({ smart: false });
+  const renderer = new commonmark.HtmlRenderer({ smart: false, safe: true });
+  return renderer.render(parser.parse(text));
+}
+
 /**
  * Build a document incrementally
  */
@@ -236,4 +242,4 @@ function pump(ast: commonmark.Node, handlers: Handlers) {
          │ └── text
          └── text
 
- */
\ No newline at end of file
+ */
diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
index f3a080b6d4..5b654a91b2 100644
--- a/packages/jsii-pacmak/lib/targets/java.ts
+++ b/packages/jsii-pacmak/lib/targets/java.ts
@@ -5,6 +5,7 @@ import path = require('path');
 import xmlbuilder = require('xmlbuilder');
 import { Generator } from '../generator';
 import logging = require('../logging');
+import { md2html } from '../markdown';
 import { PackageInfo, Target, TargetOptions } from '../target';
 import { shell } from '../util';
 import { VERSION, VERSION_DESC } from '../version';
@@ -166,6 +167,8 @@ class JavaGenerator extends Generator {
     protected onBeginAssembly(assm: spec.Assembly, fingerprint: boolean) {
         this.emitFullGeneratorInfo = fingerprint;
         this.moduleClass = this.emitModuleFile(assm);
+
+        this.emitPackageInfo(assm);
     }
 
     protected onEndAssembly(assm: spec.Assembly, fingerprint: boolean) {
@@ -346,6 +349,39 @@ class JavaGenerator extends Generator {
         }
     }
 
+    private emitPackageInfo(mod: spec.Assembly) {
+        if (!mod.docs) { return; }
+
+        const packageName = this.getNativeName(mod, undefined);
+        const packageInfoFile = this.toJavaFilePath(mod.name + '.package-info');
+        this.code.openFile(packageInfoFile);
+        this.code.line('/**');
+        if (mod.docs.summary || mod.docs.remarks) {
+            const mdown = new Array<string>();
+            if (mod.docs.summary) {
+                mdown.push(mod.docs.summary);
+            }
+            if (mod.docs.remarks) {
+                mdown.push(mod.docs.remarks);
+            }
+            for (const line of md2html(mdown.join('\n')).split('\n')) {
+                this.code.line(` * ${line}`);
+            }
+            this.code.line(' *');
+        }
+        if (mod.docs.deprecated) {
+            this.code.line(` * @deprecated ${mod.docs.deprecated}`);
+        } else if (mod.docs.stability) {
+            this.code.line(` * @stability ${mod.docs.stability}`);
+        }
+        this.code.line(' */');
+        if (mod.docs.deprecated) {
+            this.code.line('@Deprecated');
+        }
+        this.code.line(`package ${packageName};`);
+        this.code.closeFile(packageInfoFile);
+    }
+
     private emitMavenPom(assm: spec.Assembly, fingerprint: boolean) {
         const self = this;
 
@@ -441,6 +477,9 @@ class JavaGenerator extends Generator {
                                 configuration: {
                                     failOnError: false,
                                     show: 'protected',
+                                    sourceFileExcludes: {
+                                        exclude: ['**/$Module.java']
+                                    },
                                     // Adding these makes JavaDoc generation about a 3rd faster (which is far and away the most
                                     // expensive part of the build)
                                     additionalJOption: ['-J-XX:+TieredCompilation', '-J-XX:TieredStopAtLevel=1']
@@ -1161,11 +1200,11 @@ class JavaGenerator extends Generator {
 
     private getNativeName(assm: spec.Assembly, name: string | undefined): string;
     private getNativeName(assm: spec.PackageVersion, name: string | undefined, assmName: string): string;
-    private getNativeName(assm: spec.Assembly | spec.PackageVersion,
+    private getNativeName(assm: spec.Assembly | spec.PackageVersion,
                           name: string | undefined,
                           assmName: string = (assm as spec.Assembly).name): string {
         const javaPackage = assm.targets && assm.targets.java && assm.targets.java.package;
-        if (!javaPackage) { throw new Error(`The module ${assmName} does not have a java.package setting`); }
+        if (!javaPackage) { throw new Error(`The module ${assmName} does not have a java.package setting`); }
         return `${javaPackage}${name ? `.${name}` : ''}`;
     }
 
diff --git a/packages/jsii-pacmak/lib/targets/python.ts b/packages/jsii-pacmak/lib/targets/python.ts
index ac9023a0ad..8d2b884937 100644
--- a/packages/jsii-pacmak/lib/targets/python.ts
+++ b/packages/jsii-pacmak/lib/targets/python.ts
@@ -1097,7 +1097,10 @@ class Package {
         }
 
         code.openFile("README.md");
-        code.line(this.metadata.readme !== undefined ? this.metadata.readme.markdown : "");
+        const readme = this.metadata.docs && this.metadata.docs.summary
+            ? `${this.metadata.docs.summary}\n${this.metadata.docs.remarks || ''}`
+            : '';
+        code.line(readme);
         code.closeFile("README.md");
 
         // Strip " (build abcdef)" from the jsii version
@@ -1825,4 +1828,4 @@ function onelineDescription(docs: spec.Docs | undefined) {
     if (docs.remarks) { parts.push(md2rst(docs.remarks)); }
     if (docs.default) { parts.push(`Default: ${md2rst(docs.default)}`); }
     return parts.join(' ').replace(/\s+/g, ' ');
-}
\ No newline at end of file
+}
diff --git a/packages/jsii-pacmak/lib/targets/sphinx.ts b/packages/jsii-pacmak/lib/targets/sphinx.ts
index 8b9d827fa1..5c57978b6a 100644
--- a/packages/jsii-pacmak/lib/targets/sphinx.ts
+++ b/packages/jsii-pacmak/lib/targets/sphinx.ts
@@ -714,14 +714,14 @@ class SphinxDocsGenerator extends Generator {
      * @returns header: the contents of the header (or undefined)
      */
     private emitReadme(assm: spec.Assembly): { readmeFile?: string, readmeHeader?: string } {
-        if (!assm.readme) {
+        if (!assm.docs || !assm.docs.summary) {
             return {
                 readmeFile: undefined,
                 readmeHeader: undefined
             };
         }
 
-        let lines = assm.readme.markdown.split('\n');
+        let lines = [assm.docs.summary, ...(assm.docs.remarks && assm.docs.remarks.split('\n') || [])];
         let readmeHeader;
 
         if (lines[0].startsWith('# ')) {
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-base/java/pom.xml b/packages/jsii-pacmak/test/expected.jsii-calc-base/java/pom.xml
index 88fc0d326d..31681ab056 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc-base/java/pom.xml
+++ b/packages/jsii-pacmak/test/expected.jsii-calc-base/java/pom.xml
@@ -103,6 +103,9 @@
         <configuration>
           <failOnError>false</failOnError>
           <show>protected</show>
+          <sourceFileExcludes>
+            <exclude>**/$Module.java</exclude>
+          </sourceFileExcludes>
           <additionalJOption>-J-XX:+TieredCompilation</additionalJOption>
           <additionalJOption>-J-XX:TieredStopAtLevel=1</additionalJOption>
         </configuration>
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-lib/java/pom.xml b/packages/jsii-pacmak/test/expected.jsii-calc-lib/java/pom.xml
index fa52a618d8..0c52e04bf0 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc-lib/java/pom.xml
+++ b/packages/jsii-pacmak/test/expected.jsii-calc-lib/java/pom.xml
@@ -103,6 +103,9 @@
         <configuration>
           <failOnError>false</failOnError>
           <show>protected</show>
+          <sourceFileExcludes>
+            <exclude>**/$Module.java</exclude>
+          </sourceFileExcludes>
           <additionalJOption>-J-XX:+TieredCompilation</additionalJOption>
           <additionalJOption>-J-XX:TieredStopAtLevel=1</additionalJOption>
         </configuration>
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
index 7d7acac404..a78e44d478 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
@@ -182,6 +182,11 @@
     }
   },
   "description": "A simple calcuator built on JSII.",
+  "docs": {
+    "remarks": "![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n",
+    "stability": "experimental",
+    "summary": "# jsii Calculator"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -193,9 +198,6 @@
     }
   },
   "name": "jsii-calc",
-  "readme": {
-    "markdown": "# jsii Calculator\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n"
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
@@ -6810,5 +6812,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "i8GdLx7YlhttP5/pB0dKItig1wFkp/DwDdUtbYsIdfc="
+  "fingerprint": "5ejpZLVHjfmn1dghKkB/85hdGJuSRGZtxSIH+SF+b6Y="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/pom.xml b/packages/jsii-pacmak/test/expected.jsii-calc/java/pom.xml
index 29b657829b..839fcfd5e1 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/pom.xml
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/pom.xml
@@ -134,6 +134,9 @@
         <configuration>
           <failOnError>false</failOnError>
           <show>protected</show>
+          <sourceFileExcludes>
+            <exclude>**/$Module.java</exclude>
+          </sourceFileExcludes>
           <additionalJOption>-J-XX:+TieredCompilation</additionalJOption>
           <additionalJOption>-J-XX:TieredStopAtLevel=1</additionalJOption>
         </configuration>
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java
new file mode 100644
index 0000000000..c20186454e
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java
@@ -0,0 +1,14 @@
+/**
+ * <h1>jsii Calculator</h1>
+ * <p><img src="https://img.shields.io/badge/API%20Stability-experimental-important.svg" alt="API Stability: experimental" /></p>
+ * <p>This library is used to demonstrate and test the features of JSII</p>
+ * <h2>Sphinx</h2>
+ * <p>This file will be incorporated into the sphinx documentation.</p>
+ * <p>If this file starts with an &quot;H1&quot; line (in our case <code># jsii Calculator</code>), this
+ * heading will be used as the Sphinx topic name. Otherwise, the name of the module
+ * (<code>jsii-calc</code>) will be used instead.</p>
+ * 
+ *
+ * @stability experimental
+ */
+package software.amazon.jsii.tests.calculator;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/python/README.md b/packages/jsii-pacmak/test/expected.jsii-calc/python/README.md
index dead00de9c..e2a2499507 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/python/README.md
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/python/README.md
@@ -1,4 +1,5 @@
 # jsii Calculator
+![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md
index 20eea624b5..939bd4844a 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md
@@ -1,3 +1,4 @@
+![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 
diff --git a/packages/jsii-spec/lib/spec.ts b/packages/jsii-spec/lib/spec.ts
index bc87ecbcae..989f75d983 100644
--- a/packages/jsii-spec/lib/spec.ts
+++ b/packages/jsii-spec/lib/spec.ts
@@ -134,13 +134,6 @@ export interface Assembly extends Documentable {
      * @default none
      */
     types?: { [fqn: string]: Type };
-
-    /**
-     * The top-level readme document for this assembly (if any).
-     *
-     * @default none
-     */
-    readme?: { markdown: string };
 }
 
 /**
diff --git a/packages/jsii/lib/assembler.ts b/packages/jsii/lib/assembler.ts
index cdd68e57d3..604b3bc35f 100644
--- a/packages/jsii/lib/assembler.ts
+++ b/packages/jsii/lib/assembler.ts
@@ -60,11 +60,20 @@ export class Assembler implements Emitter {
         ts.DiagnosticCategory.Suggestion,
         'A "homepage" field should be specified in "package.json"');
     }
-    const readme = await _loadReadme.call(this);
-    if (!readme) {
+    const docs = await _loadReadme.call(this);
+    if (!docs || !docs.summary) {
       this._diagnostic(null,
         ts.DiagnosticCategory.Suggestion,
-        'There is not "README.md" file. It is recommended to have one.');
+        'There is no "README.md" file. It is recommended to have one.');
+    }
+
+    if (docs && docs.stability) {
+      const badge = _stabilityBadge(docs.stability);
+      if (!docs || !docs.remarks || docs.remarks.indexOf(badge) < 0) {
+        this._diagnostic(null,
+          ts.DiagnosticCategory.Error,
+          `The "README.md" file does not document the API stability (${docs.stability}). The following markdown badge is required:\n\t${badge}`);
+      }
     }
 
     this._types = {};
@@ -99,7 +108,7 @@ export class Assembler implements Emitter {
 
     const jsiiVersion = this.projectInfo.jsiiVersionFormat === 'short' ? SHORT_VERSION : VERSION;
 
-    const assembly = {
+    const assembly: spec.Assembly = {
       schema: spec.SchemaVersion.LATEST,
       name: this.projectInfo.name,
       version: this.projectInfo.version,
@@ -115,7 +124,7 @@ export class Assembler implements Emitter {
       types: this._types,
       targets: this.projectInfo.targets,
       metadata: this.projectInfo.metadata,
-      readme,
+      docs,
       jsiiVersion,
       fingerprint: '<TBD>',
     };
@@ -141,14 +150,26 @@ export class Assembler implements Emitter {
       delete this._diagnostics;
     }
 
-    async function _loadReadme(this: Assembler) {
+    async function _loadReadme(this: Assembler): Promise<spec.Docs | undefined> {
       const readmePath = path.join(this.projectInfo.projectRoot, 'README.md');
-      if (!await fs.pathExists(readmePath)) { return undefined; }
-      const renderedLines = await literate.includeAndRenderExamples(
+      if (!await fs.pathExists(readmePath)) {
+        return this.projectInfo.deprecated || this.projectInfo.stability
+          ? {
+              deprecated: this.projectInfo.deprecated,
+              stability: this.projectInfo.stability
+            }
+          : undefined;
+      }
+      const [summary, ...remarks] = await literate.includeAndRenderExamples(
         await literate.loadFromFile(readmePath),
         literate.fileSystemLoader(this.projectInfo.projectRoot)
       );
-      return { markdown: renderedLines.join('\n') };
+      return {
+        deprecated: this.projectInfo.deprecated,
+        stability: this.projectInfo.stability,
+        summary,
+        remarks: remarks.join('\n')
+      };
     }
   }
 
@@ -1629,3 +1650,18 @@ const PROHIBITED_MEMBER_NAMES = ['equals', 'hashcode'];
 function isProhibitedMemberName(name: string) {
   return PROHIBITED_MEMBER_NAMES.includes(name.toLowerCase());
 }
+
+function _stabilityBadge(stability: spec.Stability) {
+  return `![API Stability: ${stability}](https://img.shields.io/badge/API%20Stability-${stability}-${_stabilityColor()}.svg)`;
+
+  function _stabilityColor() {
+    switch (stability) {
+      case spec.Stability.Stable:
+        return 'success';
+      case spec.Stability.Experimental:
+        return 'important';
+      default:
+        return 'critical';
+    }
+  }
+}
diff --git a/packages/jsii/lib/project-info.ts b/packages/jsii/lib/project-info.ts
index 0e3c2e5a45..05c6e8d46e 100644
--- a/packages/jsii/lib/project-info.ts
+++ b/packages/jsii/lib/project-info.ts
@@ -17,6 +17,8 @@ export interface ProjectInfo {
     readonly name: string;
     readonly version: string;
     readonly author: spec.Person;
+    readonly deprecated?: string;
+    readonly stability?: spec.Stability;
     readonly license: string;
     readonly repository: {
         readonly type: string;
@@ -105,6 +107,8 @@ export async function loadProjectInfo(projectRoot: string, { fixPeerDependencies
 
         name: _required(pkg.name, 'The "package.json" file must specify the "name" attribute'),
         version: _required(pkg.version, 'The "package.json" file must specify the "version" attribute'),
+        deprecated: pkg.deprecated,
+        stability: pkg.stability && _validateStability(pkg.stability),
         author: _toPerson(_required(pkg.author, 'The "package.json" file must specify the "author" attribute'), 'author'),
         repository: {
             url: _required(pkg.repository.url, 'The "package.json" file must specify the "repository.url" attribute'),
@@ -228,3 +232,10 @@ function _validateVersionFormat(format: string): 'short' | 'full' {
     }
     return format;
 }
+
+function _validateStability(stability: string): spec.Stability {
+    if (Object.values(spec.Stability).indexOf(stability) !== -1) {
+        return stability as spec.Stability;
+    }
+    throw new Error(`Invalid stability "${stability}", it must be one of ${Object.values(spec.Stability).join(', ')}`);
+}

From c935c0f1d8f8aa65d327655b53861949f26d96ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Tue, 4 Jun 2019 10:30:21 +0200
Subject: [PATCH 2/9] PR feedback

- Moved `readme` back to it's own property
- Stopped enforcing the stability banner in readme (belongs to another tool/layer)
- Added `Stability.Deprecated`, and enforced that deprecated packages use it
- Used the NodeJS stability index in documentation
---
 packages/jsii-calc/README.md                  |  1 -
 packages/jsii-calc/test/assembly.jsii         |  9 +--
 packages/jsii-pacmak/lib/targets/java.ts      | 11 +---
 packages/jsii-pacmak/lib/targets/python.ts    |  5 +-
 packages/jsii-pacmak/lib/targets/sphinx.ts    |  4 +-
 .../.jsii                                     |  9 +--
 .../jsii/tests/calculator/package-info.java   |  1 -
 .../test/expected.jsii-calc/python/README.md  |  1 -
 .../sphinx/_jsii-calc.README.md               |  1 -
 packages/jsii-spec/lib/spec.ts                | 25 +++++++-
 packages/jsii/lib/assembler.ts                | 57 ++++++-------------
 packages/jsii/lib/project-info.ts             | 18 ++++--
 12 files changed, 67 insertions(+), 75 deletions(-)

diff --git a/packages/jsii-calc/README.md b/packages/jsii-calc/README.md
index 01b164825b..186faff39d 100644
--- a/packages/jsii-calc/README.md
+++ b/packages/jsii-calc/README.md
@@ -1,5 +1,4 @@
 # jsii Calculator
-![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
index a78e44d478..38c4555358 100644
--- a/packages/jsii-calc/test/assembly.jsii
+++ b/packages/jsii-calc/test/assembly.jsii
@@ -183,9 +183,7 @@
   },
   "description": "A simple calcuator built on JSII.",
   "docs": {
-    "remarks": "![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n",
-    "stability": "experimental",
-    "summary": "# jsii Calculator"
+    "stability": "experimental"
   },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
@@ -198,6 +196,9 @@
     }
   },
   "name": "jsii-calc",
+  "readme": {
+    "markdown": "# jsii Calculator\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
@@ -6812,5 +6813,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "5ejpZLVHjfmn1dghKkB/85hdGJuSRGZtxSIH+SF+b6Y="
+  "fingerprint": "KKOrdvjcsF9ItTXwTs/c4WE7VmYP0adJh/N9hx3+USo="
 }
diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
index 5b654a91b2..d3abd3611a 100644
--- a/packages/jsii-pacmak/lib/targets/java.ts
+++ b/packages/jsii-pacmak/lib/targets/java.ts
@@ -356,15 +356,8 @@ class JavaGenerator extends Generator {
         const packageInfoFile = this.toJavaFilePath(mod.name + '.package-info');
         this.code.openFile(packageInfoFile);
         this.code.line('/**');
-        if (mod.docs.summary || mod.docs.remarks) {
-            const mdown = new Array<string>();
-            if (mod.docs.summary) {
-                mdown.push(mod.docs.summary);
-            }
-            if (mod.docs.remarks) {
-                mdown.push(mod.docs.remarks);
-            }
-            for (const line of md2html(mdown.join('\n')).split('\n')) {
+        if (mod.readme) {
+            for (const line of md2html(mod.readme.markdown).split('\n')) {
                 this.code.line(` * ${line}`);
             }
             this.code.line(' *');
diff --git a/packages/jsii-pacmak/lib/targets/python.ts b/packages/jsii-pacmak/lib/targets/python.ts
index 8d2b884937..87879f92c4 100644
--- a/packages/jsii-pacmak/lib/targets/python.ts
+++ b/packages/jsii-pacmak/lib/targets/python.ts
@@ -1097,10 +1097,7 @@ class Package {
         }
 
         code.openFile("README.md");
-        const readme = this.metadata.docs && this.metadata.docs.summary
-            ? `${this.metadata.docs.summary}\n${this.metadata.docs.remarks || ''}`
-            : '';
-        code.line(readme);
+        code.line(this.metadata.readme && this.metadata.readme.markdown);
         code.closeFile("README.md");
 
         // Strip " (build abcdef)" from the jsii version
diff --git a/packages/jsii-pacmak/lib/targets/sphinx.ts b/packages/jsii-pacmak/lib/targets/sphinx.ts
index 5c57978b6a..8b9d827fa1 100644
--- a/packages/jsii-pacmak/lib/targets/sphinx.ts
+++ b/packages/jsii-pacmak/lib/targets/sphinx.ts
@@ -714,14 +714,14 @@ class SphinxDocsGenerator extends Generator {
      * @returns header: the contents of the header (or undefined)
      */
     private emitReadme(assm: spec.Assembly): { readmeFile?: string, readmeHeader?: string } {
-        if (!assm.docs || !assm.docs.summary) {
+        if (!assm.readme) {
             return {
                 readmeFile: undefined,
                 readmeHeader: undefined
             };
         }
 
-        let lines = [assm.docs.summary, ...(assm.docs.remarks && assm.docs.remarks.split('\n') || [])];
+        let lines = assm.readme.markdown.split('\n');
         let readmeHeader;
 
         if (lines[0].startsWith('# ')) {
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
index a78e44d478..38c4555358 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
@@ -183,9 +183,7 @@
   },
   "description": "A simple calcuator built on JSII.",
   "docs": {
-    "remarks": "![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n",
-    "stability": "experimental",
-    "summary": "# jsii Calculator"
+    "stability": "experimental"
   },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
@@ -198,6 +196,9 @@
     }
   },
   "name": "jsii-calc",
+  "readme": {
+    "markdown": "# jsii Calculator\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
@@ -6812,5 +6813,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "5ejpZLVHjfmn1dghKkB/85hdGJuSRGZtxSIH+SF+b6Y="
+  "fingerprint": "KKOrdvjcsF9ItTXwTs/c4WE7VmYP0adJh/N9hx3+USo="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java
index c20186454e..e227975f67 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java
@@ -1,6 +1,5 @@
 /**
  * <h1>jsii Calculator</h1>
- * <p><img src="https://img.shields.io/badge/API%20Stability-experimental-important.svg" alt="API Stability: experimental" /></p>
  * <p>This library is used to demonstrate and test the features of JSII</p>
  * <h2>Sphinx</h2>
  * <p>This file will be incorporated into the sphinx documentation.</p>
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/python/README.md b/packages/jsii-pacmak/test/expected.jsii-calc/python/README.md
index e2a2499507..dead00de9c 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/python/README.md
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/python/README.md
@@ -1,5 +1,4 @@
 # jsii Calculator
-![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md
index 939bd4844a..20eea624b5 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md
@@ -1,4 +1,3 @@
-![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 
diff --git a/packages/jsii-spec/lib/spec.ts b/packages/jsii-spec/lib/spec.ts
index 989f75d983..df5d05b30b 100644
--- a/packages/jsii-spec/lib/spec.ts
+++ b/packages/jsii-spec/lib/spec.ts
@@ -134,6 +134,13 @@ export interface Assembly extends Documentable {
      * @default none
      */
     types?: { [fqn: string]: Type };
+
+    /**
+     * The top-level readme document for this assembly (if any).
+     *
+     * @default none
+     */
+    readme?: { markdown: string };
 }
 
 /**
@@ -327,15 +334,27 @@ export interface Docs {
 }
 
 /**
- * API Stability levels.
+ * API Stability levels. These are modeled after the `node` stability index.
+ *
+ * @see https://nodejs.org/api/documentation.html#documentation_stability_index.
  */
 export enum Stability {
     /**
-     * Experimental APIs may change in breaking ways in a minor version update.
+     * The API may emit warnings. Backward compatibility is not guaranteed.
+     */
+    Deprecated = 'deprecated',
+
+    /**
+     * This API is still under active development and subject to non-backward
+     * compatible changes or removal in any future version. Use of the API is
+     * not recommended in production environments. Experimental APIs are not
+     * subject to the Semantic Versioning model.
      */
     Experimental = 'experimental',
+
     /**
-     * Stable APIs may not change in breaking ways without a major version bump.
+     * This API is subject to the Semantic Versioning model and may not change
+     * in breaking ways in a subsequent minor or patch version.
      */
     Stable = 'stable',
 }
diff --git a/packages/jsii/lib/assembler.ts b/packages/jsii/lib/assembler.ts
index 604b3bc35f..0fdbc9a255 100644
--- a/packages/jsii/lib/assembler.ts
+++ b/packages/jsii/lib/assembler.ts
@@ -60,21 +60,13 @@ export class Assembler implements Emitter {
         ts.DiagnosticCategory.Suggestion,
         'A "homepage" field should be specified in "package.json"');
     }
-    const docs = await _loadReadme.call(this);
-    if (!docs || !docs.summary) {
+    const readme = await _loadReadme.call(this);
+    if (readme == null) {
       this._diagnostic(null,
         ts.DiagnosticCategory.Suggestion,
         'There is no "README.md" file. It is recommended to have one.');
     }
-
-    if (docs && docs.stability) {
-      const badge = _stabilityBadge(docs.stability);
-      if (!docs || !docs.remarks || docs.remarks.indexOf(badge) < 0) {
-        this._diagnostic(null,
-          ts.DiagnosticCategory.Error,
-          `The "README.md" file does not document the API stability (${docs.stability}). The following markdown badge is required:\n\t${badge}`);
-      }
-    }
+    const docs = _loadDocs.call(this);
 
     this._types = {};
     this._deferred = [];
@@ -125,6 +117,7 @@ export class Assembler implements Emitter {
       targets: this.projectInfo.targets,
       metadata: this.projectInfo.metadata,
       docs,
+      readme,
       jsiiVersion,
       fingerprint: '<TBD>',
     };
@@ -150,26 +143,25 @@ export class Assembler implements Emitter {
       delete this._diagnostics;
     }
 
-    async function _loadReadme(this: Assembler): Promise<spec.Docs | undefined> {
+    async function _loadReadme(this: Assembler) {
       const readmePath = path.join(this.projectInfo.projectRoot, 'README.md');
       if (!await fs.pathExists(readmePath)) {
-        return this.projectInfo.deprecated || this.projectInfo.stability
-          ? {
-              deprecated: this.projectInfo.deprecated,
-              stability: this.projectInfo.stability
-            }
-          : undefined;
+        return undefined;
       }
-      const [summary, ...remarks] = await literate.includeAndRenderExamples(
+      const markdown = await literate.includeAndRenderExamples(
         await literate.loadFromFile(readmePath),
         literate.fileSystemLoader(this.projectInfo.projectRoot)
       );
-      return {
-        deprecated: this.projectInfo.deprecated,
-        stability: this.projectInfo.stability,
-        summary,
-        remarks: remarks.join('\n')
-      };
+      return { markdown: markdown.join('\n') };
+    }
+
+    function _loadDocs(this: Assembler): spec.Docs | undefined {
+      if (!this.projectInfo.stability && !this.projectInfo.deprecated) {
+        return undefined;
+      }
+      const deprecated = this.projectInfo.deprecated;
+      const stability = this.projectInfo.stability;
+      return { deprecated, stability };
     }
   }
 
@@ -1650,18 +1642,3 @@ const PROHIBITED_MEMBER_NAMES = ['equals', 'hashcode'];
 function isProhibitedMemberName(name: string) {
   return PROHIBITED_MEMBER_NAMES.includes(name.toLowerCase());
 }
-
-function _stabilityBadge(stability: spec.Stability) {
-  return `![API Stability: ${stability}](https://img.shields.io/badge/API%20Stability-${stability}-${_stabilityColor()}.svg)`;
-
-  function _stabilityColor() {
-    switch (stability) {
-      case spec.Stability.Stable:
-        return 'success';
-      case spec.Stability.Experimental:
-        return 'important';
-      default:
-        return 'critical';
-    }
-  }
-}
diff --git a/packages/jsii/lib/project-info.ts b/packages/jsii/lib/project-info.ts
index 05c6e8d46e..764068b8a5 100644
--- a/packages/jsii/lib/project-info.ts
+++ b/packages/jsii/lib/project-info.ts
@@ -108,7 +108,7 @@ export async function loadProjectInfo(projectRoot: string, { fixPeerDependencies
         name: _required(pkg.name, 'The "package.json" file must specify the "name" attribute'),
         version: _required(pkg.version, 'The "package.json" file must specify the "version" attribute'),
         deprecated: pkg.deprecated,
-        stability: pkg.stability && _validateStability(pkg.stability),
+        stability: _validateStability(pkg.stability, pkg.deprecated),
         author: _toPerson(_required(pkg.author, 'The "package.json" file must specify the "author" attribute'), 'author'),
         repository: {
             url: _required(pkg.repository.url, 'The "package.json" file must specify the "repository.url" attribute'),
@@ -233,9 +233,17 @@ function _validateVersionFormat(format: string): 'short' | 'full' {
     return format;
 }
 
-function _validateStability(stability: string): spec.Stability {
-    if (Object.values(spec.Stability).indexOf(stability) !== -1) {
-        return stability as spec.Stability;
+function _validateStability(stability: string | undefined, deprecated: string | undefined): spec.Stability | undefined {
+    if (!stability && deprecated) {
+        stability = spec.Stability.Deprecated;
+    } else if (deprecated && stability !== spec.Stability.Deprecated) {
+        throw new Error(`Package is deprecated (${deprecated}), but it's stability is ${stability} and not ${spec.Stability.Deprecated}`);
     }
-    throw new Error(`Invalid stability "${stability}", it must be one of ${Object.values(spec.Stability).join(', ')}`);
+    if (!stability) {
+        return undefined;
+    }
+    if (Object.values(spec.Stability).indexOf(stability) === -1) {
+        throw new Error(`Invalid stability "${stability}", it must be one of ${Object.values(spec.Stability).join(', ')}`);
+    }
+    return stability as spec.Stability;
 }

From 755f17f71262b945ed77efe761b339b4b556bbf0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Tue, 4 Jun 2019 14:11:51 +0200
Subject: [PATCH 3/9] More PR feedback

---
 packages/jsii-pacmak/lib/targets/java.ts | 3 +++
 packages/jsii-spec/lib/spec.ts           | 3 +++
 packages/jsii/lib/assembler.ts           | 8 +++-----
 3 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
index d3abd3611a..ae8a3dff0a 100644
--- a/packages/jsii-pacmak/lib/targets/java.ts
+++ b/packages/jsii-pacmak/lib/targets/java.ts
@@ -471,6 +471,9 @@ class JavaGenerator extends Generator {
                                     failOnError: false,
                                     show: 'protected',
                                     sourceFileExcludes: {
+                                        // Excluding the $Module classes so they won't pollute the docsite. They otherwise
+                                        // are all collected at the top of the classlist, burrying useful information under
+                                        // a lot of dry scrolling.
                                         exclude: ['**/$Module.java']
                                     },
                                     // Adding these makes JavaDoc generation about a 3rd faster (which is far and away the most
diff --git a/packages/jsii-spec/lib/spec.ts b/packages/jsii-spec/lib/spec.ts
index df5d05b30b..d47bba6f48 100644
--- a/packages/jsii-spec/lib/spec.ts
+++ b/packages/jsii-spec/lib/spec.ts
@@ -341,6 +341,9 @@ export interface Docs {
 export enum Stability {
     /**
      * The API may emit warnings. Backward compatibility is not guaranteed.
+     *
+     * More information about the deprecation can usually be found in the
+     * `deprecated` field.
      */
     Deprecated = 'deprecated',
 
diff --git a/packages/jsii/lib/assembler.ts b/packages/jsii/lib/assembler.ts
index 0fdbc9a255..49cf73f74c 100644
--- a/packages/jsii/lib/assembler.ts
+++ b/packages/jsii/lib/assembler.ts
@@ -145,14 +145,12 @@ export class Assembler implements Emitter {
 
     async function _loadReadme(this: Assembler) {
       const readmePath = path.join(this.projectInfo.projectRoot, 'README.md');
-      if (!await fs.pathExists(readmePath)) {
-        return undefined;
-      }
-      const markdown = await literate.includeAndRenderExamples(
+      if (!await fs.pathExists(readmePath)) { return undefined; }
+      const renderedLines = await literate.includeAndRenderExamples(
         await literate.loadFromFile(readmePath),
         literate.fileSystemLoader(this.projectInfo.projectRoot)
       );
-      return { markdown: markdown.join('\n') };
+      return { markdown: renderedLines.join('\n') };
     }
 
     function _loadDocs(this: Assembler): spec.Docs | undefined {

From 03b2e4c211e09f13bc39dc6fa4ce2d1e190773d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Tue, 4 Jun 2019 16:04:12 +0200
Subject: [PATCH 4/9] Add tests & some improvements

---
 packages/jsii-calc/lib/compliance.ts          | 33 ++++++-
 packages/jsii-calc/test/assembly.jsii         | 99 +++++++++++++++++--
 .../Class/ClassGenerator.cs                   | 51 ++++++++--
 .../Enum/EnumGenerator.cs                     | 26 ++++-
 .../Interface/InterfaceGenerator.cs           | 25 ++++-
 .../MethodGeneratorBase.cs                    | 20 +++-
 .../PropertyGeneratorBase.cs                  | 20 +++-
 .../Amazon.JSII.JsonModel/Spec/Stability.cs   |  3 +-
 packages/jsii-pacmak/lib/targets/java.ts      |  6 ++
 .../.jsii                                     | 99 +++++++++++++++++--
 .../CalculatorNamespace/ClassWithDocs.cs      |  1 -
 .../CalculatorNamespace/DeprecatedClass.cs    | 63 ++++++++++++
 .../JSII/Tests/CalculatorNamespace/Old.cs     |  6 +-
 .../amazon/jsii/tests/calculator/$Module.java |  1 +
 .../jsii/tests/calculator/ClassWithDocs.java  |  1 -
 .../tests/calculator/DeprecatedClass.java     | 65 ++++++++++++
 .../amazon/jsii/tests/calculator/Old.java     |  1 +
 .../python/src/jsii_calc/__init__.py          | 52 +++++++++-
 .../expected.jsii-calc/sphinx/jsii-calc.rst   | 50 ++++++++++
 packages/jsii-spec/lib/spec.ts                | 11 +++
 packages/jsii/lib/docs.ts                     | 13 ++-
 21 files changed, 592 insertions(+), 54 deletions(-)
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java

diff --git a/packages/jsii-calc/lib/compliance.ts b/packages/jsii-calc/lib/compliance.ts
index b10e3f16cd..016fcf559c 100644
--- a/packages/jsii-calc/lib/compliance.ts
+++ b/packages/jsii-calc/lib/compliance.ts
@@ -1631,7 +1631,6 @@ export interface OptionalStruct {
  *
  * @see https://aws.amazon.com/
  * @customAttribute hasAValue
- * @deprecated Use something else please
  * @stable
  */
 export class ClassWithDocs {
@@ -1682,3 +1681,35 @@ export abstract class VoidCallback {
     }
     protected abstract overrideMe(): void;
 }
+
+/**
+ * This tests code generation of deprecation markers
+ *
+ * @deprecated without replacement
+ */
+export class DeprecatedClass {
+    /**
+     * @deprecated intentionally
+     */
+    public readonly deprecatedAttribute: string;
+
+    /**
+     * @deprecated can be unexpectedly non-null!
+     */
+    protected deprecatedProtected?: string;
+
+    /**
+     * @param argument some string
+     * @deprecated this is unsafe
+     */
+    constructor(argument = 'tombstone!') {
+        this.deprecatedAttribute = argument;
+    }
+
+    /**
+     * @deprecated throws unexpected errors
+     */
+    public deprecatedMethod() {
+        throw new Error();
+    }
+}
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
index 38c4555358..c51241fdb4 100644
--- a/packages/jsii-calc/test/assembly.jsii
+++ b/packages/jsii-calc/test/assembly.jsii
@@ -1518,7 +1518,6 @@
         "custom": {
           "customAttribute": "hasAValue"
         },
-        "deprecated": "Use something else please",
         "example": "function anExample() {\n}",
         "remarks": "The docs are great. They're a bunch of tags.",
         "see": "https://aws.amazon.com/",
@@ -1530,7 +1529,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/compliance.ts",
-        "line": 1637
+        "line": 1636
       },
       "name": "ClassWithDocs"
     },
@@ -1890,6 +1889,85 @@
         }
       ]
     },
+    "jsii-calc.DeprecatedClass": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "deprecated": "without replacement",
+        "stability": "deprecated",
+        "summary": "This tests code generation of deprecation markers."
+      },
+      "fqn": "jsii-calc.DeprecatedClass",
+      "initializer": {
+        "docs": {
+          "deprecated": "this is unsafe",
+          "stability": "deprecated"
+        },
+        "parameters": [
+          {
+            "docs": {
+              "summary": "some string."
+            },
+            "name": "argument",
+            "optional": true,
+            "type": {
+              "primitive": "string"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 1690
+      },
+      "methods": [
+        {
+          "docs": {
+            "deprecated": "throws unexpected errors",
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 1712
+          },
+          "name": "deprecatedMethod"
+        }
+      ],
+      "name": "DeprecatedClass",
+      "properties": [
+        {
+          "docs": {
+            "deprecated": "intentionally",
+            "stability": "deprecated"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 1694
+          },
+          "name": "deprecatedAttribute",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "docs": {
+            "deprecated": "can be unexpectedly non-null!",
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 1699
+          },
+          "name": "deprecatedProtected",
+          "optional": true,
+          "protected": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
+    },
     "jsii-calc.DerivedClassHasNoProperties.Base": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.DerivedClassHasNoProperties.Base",
@@ -4831,6 +4909,7 @@
       "assembly": "jsii-calc",
       "docs": {
         "deprecated": "Use the new class",
+        "stability": "deprecated",
         "summary": "Old class."
       },
       "fqn": "jsii-calc.Old",
@@ -5676,13 +5755,13 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/compliance.ts",
-        "line": 1645
+        "line": 1644
       },
       "methods": [
         {
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1648
+            "line": 1647
           },
           "name": "canAccessStaticContext",
           "returns": {
@@ -5698,7 +5777,7 @@
         {
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1656
+            "line": 1655
           },
           "name": "staticVariable",
           "static": true,
@@ -6632,13 +6711,13 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/compliance.ts",
-        "line": 1674
+        "line": 1673
       },
       "methods": [
         {
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1679
+            "line": 1678
           },
           "name": "callMe"
         },
@@ -6646,7 +6725,7 @@
           "abstract": true,
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1683
+            "line": 1682
           },
           "name": "overrideMe",
           "protected": true
@@ -6658,7 +6737,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1676
+            "line": 1675
           },
           "name": "methodWasCalled",
           "type": {
@@ -6813,5 +6892,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "KKOrdvjcsF9ItTXwTs/c4WE7VmYP0adJh/N9hx3+USo="
+  "fingerprint": "5R2rpEqEYZnuiNa8EnVDEierWuf4xkcuVJDj4a7hNPk="
 }
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Class/ClassGenerator.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Class/ClassGenerator.cs
index 2385bab2fd..c0b644177f 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Class/ClassGenerator.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Class/ClassGenerator.cs
@@ -40,14 +40,31 @@ SyntaxList<AttributeListSyntax> CreateAttributes()
                     argumentList += $", parametersJson: {parametersJsonLiteral}";
                 }
                 
-                return SF.List(new[] {
-                    SF.AttributeList(SF.SeparatedList(new[] {
+                return SF.List(GetAttributeLists());
+
+                IEnumerable<AttributeListSyntax> GetAttributeLists()
+                {
+                    yield return SF.AttributeList(SF.SeparatedList(new[] {
                         SF.Attribute(
                             SF.ParseName("JsiiClass"),
                             SF.ParseAttributeArgumentList($"({argumentList})")
                         )
-                    }))
-                });
+                    }));
+
+                    if (Type.Docs?.Deprecated != null)
+                    {
+                        yield return SF.AttributeList(SF.SeparatedList(new[] {
+                            SF.Attribute(
+                                SF.ParseName("System.Obsolete"),
+                                SF.AttributeArgumentList(
+                                    SF.SingletonSeparatedList(
+                                        SF.AttributeArgument(SF.LiteralExpression(SyntaxKind.StringLiteralExpression, SF.Literal(Type.Docs.Deprecated)))
+                                    )
+                                )
+                            )
+                        }));
+                    }
+                }
             }
 
             SyntaxTokenList CreateModifiers()
@@ -102,12 +119,13 @@ IEnumerable<MemberDeclarationSyntax> CreateMembers()
         IEnumerable<MemberDeclarationSyntax> CreateConstructors()
         {
             SyntaxToken typeName = Symbols.GetNameSyntaxToken(Type);
+            var attributes = GetAttributeLists();
 
             if (Type.Initializer != null)
             {
                 yield return SF.ConstructorDeclaration
                 (
-                    SF.List<AttributeListSyntax>(),
+                    attributes,
                     SF.TokenList(SF.Token(
                         Type.IsAbstract || Type.Initializer.IsProtected
                             ? SyntaxKind.ProtectedKeyword
@@ -141,7 +159,7 @@ IEnumerable<MemberDeclarationSyntax> CreateConstructors()
 
             yield return SF.ConstructorDeclaration
             (
-                SF.List<AttributeListSyntax>(),
+                attributes,
                 SF.TokenList(SF.Token(SyntaxKind.ProtectedKeyword)),
                 typeName,
                 SF.ParseParameterList("(ByRefValue reference)"),
@@ -157,7 +175,7 @@ IEnumerable<MemberDeclarationSyntax> CreateConstructors()
             // This constructor allows child classes to supply their own parameter lists. It is always protected.
             yield return SF.ConstructorDeclaration
             (
-                SF.List<AttributeListSyntax>(),
+                attributes,
                 SF.TokenList(SF.Token(SyntaxKind.ProtectedKeyword)),
                 typeName,
                 SF.ParseParameterList("(DeputyProps props)"),
@@ -192,6 +210,25 @@ ArgumentSyntax GetBaseArgument()
                     )
                 );
             }
+
+            SyntaxList<AttributeListSyntax> GetAttributeLists()
+            {
+                var deprecated = Type.Initializer?.Docs?.Deprecated;
+                if (deprecated == null)
+                {
+                    return SF.List<AttributeListSyntax>();
+                }
+                return SF.List(new[] { SF.AttributeList(SF.SingletonSeparatedList(
+                    SF.Attribute(
+                        SF.ParseName("System.Obsolete"),
+                        SF.AttributeArgumentList(
+                            SF.SingletonSeparatedList(
+                                SF.AttributeArgument(SF.LiteralExpression(SyntaxKind.StringLiteralExpression, SF.Literal(deprecated)))
+                            )
+                        )
+                    )
+                )) });
+            }
         }
 
         IEnumerable<PropertyDeclarationSyntax> CreateProperties()
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Enum/EnumGenerator.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Enum/EnumGenerator.cs
index 0b1dc457f0..0105794202 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Enum/EnumGenerator.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Enum/EnumGenerator.cs
@@ -3,6 +3,7 @@
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
+using System.Collections.Generic;
 using System.Linq;
 using SF = Microsoft.CodeAnalysis.CSharp.SyntaxFactory;
 
@@ -32,14 +33,31 @@ SyntaxList<AttributeListSyntax> CreateAttributes()
             TypeOfExpressionSyntax typeOfExpression = SF.TypeOfExpression(Symbols.GetNameSyntax(Type));
             SyntaxToken fullyQualifiedNameLiteral = SF.Literal(Type.FullyQualifiedName);
 
-            return SF.List(new[] {
-                SF.AttributeList(SF.SeparatedList(new[] {
+            return SF.List(GetAttributeLists());
+
+            IEnumerable<AttributeListSyntax> GetAttributeLists()
+            {
+                yield return SF.AttributeList(SF.SeparatedList(new[] {
                     SF.Attribute(
                         SF.ParseName("JsiiEnum"),
                         SF.ParseAttributeArgumentList($"(nativeType: {typeOfExpression}, fullyQualifiedName: {fullyQualifiedNameLiteral})")
                     )
-                }))
-            });
+                }));
+
+                if (Type.Docs?.Deprecated != null)
+                {
+                    yield return SF.AttributeList(SF.SeparatedList(new[] {
+                            SF.Attribute(
+                                SF.ParseName("System.Obsolete"),
+                                SF.AttributeArgumentList(
+                                    SF.SingletonSeparatedList(
+                                        SF.AttributeArgument(SF.LiteralExpression(SyntaxKind.StringLiteralExpression, SF.Literal(Type.Docs.Deprecated)))
+                                    )
+                                )
+                            )
+                        }));
+                }
+            }
         }
 
         SeparatedSyntaxList<EnumMemberDeclarationSyntax> CreateValues()
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Interface/InterfaceGenerator.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Interface/InterfaceGenerator.cs
index 1cd3fecb29..0417f772ca 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Interface/InterfaceGenerator.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Interface/InterfaceGenerator.cs
@@ -34,14 +34,31 @@ SyntaxList<AttributeListSyntax> CreateAttributes()
                 TypeOfExpressionSyntax typeOfExpression = SF.TypeOfExpression(Symbols.GetNameSyntax(Type));
                 SyntaxToken fullyQualifiedNameLiteral = SF.Literal(Type.FullyQualifiedName);
 
-                return SF.List(new[] {
-                    SF.AttributeList(SF.SeparatedList(new[] {
+                return SF.List(GetAttributeLists());
+
+                IEnumerable<AttributeListSyntax> GetAttributeLists()
+                {
+                    yield return SF.AttributeList(SF.SeparatedList(new[] {
                         SF.Attribute(
                             SF.ParseName("JsiiInterface"),
                             SF.ParseAttributeArgumentList($"(nativeType: {typeOfExpression}, fullyQualifiedName: {fullyQualifiedNameLiteral})")
                         )
-                    }))
-                });
+                    }));
+
+                    if (Type.Docs?.Deprecated != null)
+                    {
+                        yield return SF.AttributeList(SF.SeparatedList(new[] {
+                            SF.Attribute(
+                                SF.ParseName("System.Obsolete"),
+                                SF.AttributeArgumentList(
+                                    SF.SingletonSeparatedList(
+                                        SF.AttributeArgument(SF.LiteralExpression(SyntaxKind.StringLiteralExpression, SF.Literal(Type.Docs.Deprecated)))
+                                    )
+                                )
+                            )
+                        }));
+                    }
+                }
             }
 
             BaseListSyntax CreateBaseList()
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/MethodGeneratorBase.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/MethodGeneratorBase.cs
index 11542d27a4..bb3d369d90 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/MethodGeneratorBase.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/MethodGeneratorBase.cs
@@ -167,9 +167,9 @@ IEnumerable<ExpressionSyntax> GetArguments()
 
         SyntaxList<AttributeListSyntax> GetAttributeLists()
         {
-            return SF.List(new[] { SF.AttributeList(SF.SeparatedList(GetAttributes())) });
+            return SF.List(GetAttributeLists());
 
-            IEnumerable<AttributeSyntax> GetAttributes()
+            IEnumerable<AttributeListSyntax> GetAttributeLists()
             {
                 SyntaxToken nameLiteral = SF.Literal(Method.Name);
                 SyntaxToken trueLiteral = SF.Token(SyntaxKind.TrueKeyword);
@@ -197,10 +197,22 @@ IEnumerable<AttributeSyntax> GetAttributes()
                     argumentList += $", isOverride: {trueLiteral}";
                 }
 
-                yield return SF.Attribute(
+                yield return SF.AttributeList(SF.SingletonSeparatedList(SF.Attribute(
                     SF.ParseName("JsiiMethod"),
                     SF.ParseAttributeArgumentList($"({argumentList})")
-                );
+                )));
+
+                if (Method.Docs?.Deprecated != null)
+                {
+                    yield return SF.AttributeList(SF.SingletonSeparatedList(SF.Attribute(
+                        SF.ParseName("System.Obsolete"),
+                        SF.AttributeArgumentList(
+                            SF.SingletonSeparatedList(
+                                SF.AttributeArgument(SF.LiteralExpression(SyntaxKind.StringLiteralExpression, SF.Literal(Method.Docs.Deprecated)))
+                            )
+                        )
+                    )));
+                }
             }
         }
 
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/PropertyGeneratorBase.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/PropertyGeneratorBase.cs
index 3ca2e33ab1..17b08475fe 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/PropertyGeneratorBase.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/PropertyGeneratorBase.cs
@@ -157,9 +157,9 @@ SyntaxTokenList GetModifierList()
         
         SyntaxList<AttributeListSyntax> GetAttributeLists()
         {
-            return SF.List(new[] { SF.AttributeList(SF.SeparatedList(GetAttributes())) });
+            return SF.List(GetAttributesLists());
 
-            IEnumerable<AttributeSyntax> GetAttributes()
+            IEnumerable<AttributeListSyntax> GetAttributesLists()
             {
                 SyntaxToken nameLiteral = SF.Literal(Property.Name);
                 SyntaxToken typeJsonLiteral = SF.Literal(JsonConvert.SerializeObject(Property.Type, SerializerSettings));
@@ -175,10 +175,22 @@ IEnumerable<AttributeSyntax> GetAttributes()
                     argumentList += $", isOverride: {trueLiteral}";
                 }
 
-                yield return SF.Attribute(
+                yield return SF.AttributeList(SF.SingletonSeparatedList(SF.Attribute(
                     SF.ParseName("JsiiProperty"),
                     SF.ParseAttributeArgumentList($"({argumentList})")
-                );
+                )));
+
+                if (Property.Docs?.Deprecated != null)
+                {
+                    yield return SF.AttributeList(SF.SingletonSeparatedList(SF.Attribute(
+                        SF.ParseName("System.Obsolete"),
+                        SF.AttributeArgumentList(
+                            SF.SingletonSeparatedList(
+                                SF.AttributeArgument(SF.LiteralExpression(SyntaxKind.StringLiteralExpression, SF.Literal(Property.Docs.Deprecated)))
+                            )
+                        )
+                    )));
+                }
             }
         }
 
diff --git a/packages/jsii-dotnet-jsonmodel/src/Amazon.JSII.JsonModel/Spec/Stability.cs b/packages/jsii-dotnet-jsonmodel/src/Amazon.JSII.JsonModel/Spec/Stability.cs
index 788dfb09c9..e6edb4e2c6 100644
--- a/packages/jsii-dotnet-jsonmodel/src/Amazon.JSII.JsonModel/Spec/Stability.cs
+++ b/packages/jsii-dotnet-jsonmodel/src/Amazon.JSII.JsonModel/Spec/Stability.cs
@@ -7,6 +7,7 @@ namespace Amazon.JSII.JsonModel.Spec
     public enum Stability
     {
         Stable,
-        Experimental
+        Experimental,
+        Deprecated
     }
 }
diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
index ae8a3dff0a..b891c13562 100644
--- a/packages/jsii-pacmak/lib/targets/java.ts
+++ b/packages/jsii-pacmak/lib/targets/java.ts
@@ -197,6 +197,7 @@ class JavaGenerator extends Generator {
         const inner = nested ? ' static' : '';
         const absPrefix = abstract ? ' abstract' : '';
 
+        if (spec.isDeprecated(cls)) { this.code.line('@Deprecated'); }
         if (!nested) { this.emitGeneratedAnnotation(); }
         this.code.line(`@software.amazon.jsii.Jsii(module = ${this.moduleClass}.class, fqn = "${cls.fqn}")`);
         this.code.openBlock(`public${inner}${absPrefix} class ${cls.name}${extendsExpression}${implementsExpr}`);
@@ -216,6 +217,7 @@ class JavaGenerator extends Generator {
 
     protected onInitializer(cls: spec.ClassType, method: spec.Method) {
         this.addJavaDocs(method);
+        if (spec.isDeprecated(method)) { this.code.line('@Deprecated'); }
         this.code.openBlock(`${this.renderAccessLevel(method)} ${cls.name}(${this.renderMethodParameters(method)})`);
         this.code.line('super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);');
         this.code.line(`software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this${this.renderMethodCallArguments(method)});`);
@@ -581,6 +583,7 @@ class JavaGenerator extends Generator {
         const access = this.renderAccessLevel(prop);
 
         this.addJavaDocs(prop);
+        if (spec.isDeprecated(prop)) { this.code.line('@Deprecated'); }
         this.code.line(`${access} final static ${propType} ${propName};`);
     }
 
@@ -598,6 +601,7 @@ class JavaGenerator extends Generator {
             this.code.line();
             this.addJavaDocs(prop);
             if (overrides) { this.code.line('@Override'); }
+            if (spec.isDeprecated(prop)) { this.code.line('@Deprecated'); }
             if (isNullable(prop)) { this.code.line(JSR305_NULLABLE); }
             this.code.openBlock(`${access} ${statc}${getterType} get${propName}()`);
 
@@ -619,6 +623,7 @@ class JavaGenerator extends Generator {
                 this.code.line();
                 this.addJavaDocs(prop);
                 if (overrides) { this.code.line('@Override'); }
+                if (spec.isDeprecated(prop)) { this.code.line('@Deprecated'); }
                 const nullable = isNullable(prop) ? `${JSR305_NULLABLE} ` : '';
                 this.code.openBlock(`${access} ${statc}void set${propName}(${nullable}final ${type} value)`);
                 let statement = '';
@@ -645,6 +650,7 @@ class JavaGenerator extends Generator {
         const signature = `${returnType} ${methodName}(${this.renderMethodParameters(method)})`;
         this.code.line();
         this.addJavaDocs(method);
+        if (spec.isDeprecated(method)) { this.code.line('@Deprecated'); }
         if (overrides) { this.code.line('@Override'); }
         if (isNullable(method.returns)) { this.code.line(JSR305_NULLABLE); }
         if (method.abstract) {
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
index 38c4555358..c51241fdb4 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
@@ -1518,7 +1518,6 @@
         "custom": {
           "customAttribute": "hasAValue"
         },
-        "deprecated": "Use something else please",
         "example": "function anExample() {\n}",
         "remarks": "The docs are great. They're a bunch of tags.",
         "see": "https://aws.amazon.com/",
@@ -1530,7 +1529,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/compliance.ts",
-        "line": 1637
+        "line": 1636
       },
       "name": "ClassWithDocs"
     },
@@ -1890,6 +1889,85 @@
         }
       ]
     },
+    "jsii-calc.DeprecatedClass": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "deprecated": "without replacement",
+        "stability": "deprecated",
+        "summary": "This tests code generation of deprecation markers."
+      },
+      "fqn": "jsii-calc.DeprecatedClass",
+      "initializer": {
+        "docs": {
+          "deprecated": "this is unsafe",
+          "stability": "deprecated"
+        },
+        "parameters": [
+          {
+            "docs": {
+              "summary": "some string."
+            },
+            "name": "argument",
+            "optional": true,
+            "type": {
+              "primitive": "string"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 1690
+      },
+      "methods": [
+        {
+          "docs": {
+            "deprecated": "throws unexpected errors",
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 1712
+          },
+          "name": "deprecatedMethod"
+        }
+      ],
+      "name": "DeprecatedClass",
+      "properties": [
+        {
+          "docs": {
+            "deprecated": "intentionally",
+            "stability": "deprecated"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 1694
+          },
+          "name": "deprecatedAttribute",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "docs": {
+            "deprecated": "can be unexpectedly non-null!",
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 1699
+          },
+          "name": "deprecatedProtected",
+          "optional": true,
+          "protected": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
+    },
     "jsii-calc.DerivedClassHasNoProperties.Base": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.DerivedClassHasNoProperties.Base",
@@ -4831,6 +4909,7 @@
       "assembly": "jsii-calc",
       "docs": {
         "deprecated": "Use the new class",
+        "stability": "deprecated",
         "summary": "Old class."
       },
       "fqn": "jsii-calc.Old",
@@ -5676,13 +5755,13 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/compliance.ts",
-        "line": 1645
+        "line": 1644
       },
       "methods": [
         {
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1648
+            "line": 1647
           },
           "name": "canAccessStaticContext",
           "returns": {
@@ -5698,7 +5777,7 @@
         {
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1656
+            "line": 1655
           },
           "name": "staticVariable",
           "static": true,
@@ -6632,13 +6711,13 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/compliance.ts",
-        "line": 1674
+        "line": 1673
       },
       "methods": [
         {
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1679
+            "line": 1678
           },
           "name": "callMe"
         },
@@ -6646,7 +6725,7 @@
           "abstract": true,
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1683
+            "line": 1682
           },
           "name": "overrideMe",
           "protected": true
@@ -6658,7 +6737,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/compliance.ts",
-            "line": 1676
+            "line": 1675
           },
           "name": "methodWasCalled",
           "type": {
@@ -6813,5 +6892,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "KKOrdvjcsF9ItTXwTs/c4WE7VmYP0adJh/N9hx3+USo="
+  "fingerprint": "5R2rpEqEYZnuiNa8EnVDEierWuf4xkcuVJDj4a7hNPk="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ClassWithDocs.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ClassWithDocs.cs
index cf642d45a0..4cb1a27104 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ClassWithDocs.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ClassWithDocs.cs
@@ -5,7 +5,6 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
     /// <summary>This class has docs.</summary>
     /// <remarks>
     /// The docs are great. They're a bunch of tags.
-    /// deprecated: Use something else please
     /// stability: Stable
     /// example:
     /// &lt;code&gt;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
new file mode 100644
index 0000000000..533f8cc932
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
@@ -0,0 +1,63 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <summary>This tests code generation of deprecation markers.</summary>
+    /// <remarks>
+    /// deprecated: without replacement
+    /// stability: Deprecated
+    /// </remarks>
+    [JsiiClass(nativeType: typeof(DeprecatedClass), fullyQualifiedName: "jsii-calc.DeprecatedClass", parametersJson: "[{\"name\":\"argument\",\"type\":{\"primitive\":\"string\"},\"optional\":true}]")]
+    [System.Obsolete("without replacement")]
+    public class DeprecatedClass : DeputyBase
+    {
+        [System.Obsolete("this is unsafe")]
+        public DeprecatedClass(string argument): base(new DeputyProps(new object[]{argument}))
+        {
+        }
+
+        [System.Obsolete("this is unsafe")]
+        protected DeprecatedClass(ByRefValue reference): base(reference)
+        {
+        }
+
+        [System.Obsolete("this is unsafe")]
+        protected DeprecatedClass(DeputyProps props): base(props)
+        {
+        }
+
+        /// <remarks>
+        /// deprecated: intentionally
+        /// stability: Deprecated
+        /// </remarks>
+        [JsiiProperty(name: "deprecatedAttribute", typeJson: "{\"primitive\":\"string\"}")]
+        [System.Obsolete("intentionally")]
+        public virtual string DeprecatedAttribute
+        {
+            get => GetInstanceProperty<string>();
+        }
+
+        /// <remarks>
+        /// deprecated: can be unexpectedly non-null!
+        /// stability: Deprecated
+        /// </remarks>
+        [JsiiProperty(name: "deprecatedProtected", typeJson: "{\"primitive\":\"string\"}", isOptional: true)]
+        [System.Obsolete("can be unexpectedly non-null!")]
+        protected virtual string DeprecatedProtected
+        {
+            get => GetInstanceProperty<string>();
+            set => SetInstanceProperty(value);
+        }
+
+        /// <remarks>
+        /// deprecated: throws unexpected errors
+        /// stability: Deprecated
+        /// </remarks>
+        [JsiiMethod(name: "deprecatedMethod")]
+        [System.Obsolete("throws unexpected errors")]
+        public virtual void DeprecatedMethod()
+        {
+            InvokeInstanceVoidMethod(new object[]{});
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Old.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Old.cs
index 3391b74a7f..18a49b7c9a 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Old.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Old.cs
@@ -3,8 +3,12 @@
 namespace Amazon.JSII.Tests.CalculatorNamespace
 {
     /// <summary>Old class.</summary>
-    /// <remarks>deprecated: Use the new class</remarks>
+    /// <remarks>
+    /// deprecated: Use the new class
+    /// stability: Deprecated
+    /// </remarks>
     [JsiiClass(nativeType: typeof(Old), fullyQualifiedName: "jsii-calc.Old")]
+    [System.Obsolete("Use the new class")]
     public class Old : DeputyBase
     {
         public Old(): base(new DeputyProps(new object[]{}))
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
index 0156239c12..02c68fab10 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
@@ -39,6 +39,7 @@ protected Class<?> resolveClass(final String fqn) throws ClassNotFoundException
             case "jsii-calc.Constructors": return software.amazon.jsii.tests.calculator.Constructors.class;
             case "jsii-calc.ConsumersOfThisCrazyTypeSystem": return software.amazon.jsii.tests.calculator.ConsumersOfThisCrazyTypeSystem.class;
             case "jsii-calc.DefaultedConstructorArgument": return software.amazon.jsii.tests.calculator.DefaultedConstructorArgument.class;
+            case "jsii-calc.DeprecatedClass": return software.amazon.jsii.tests.calculator.DeprecatedClass.class;
             case "jsii-calc.DerivedClassHasNoProperties.Base": return software.amazon.jsii.tests.calculator.DerivedClassHasNoProperties.Base.class;
             case "jsii-calc.DerivedClassHasNoProperties.Derived": return software.amazon.jsii.tests.calculator.DerivedClassHasNoProperties.Derived.class;
             case "jsii-calc.DerivedStruct": return software.amazon.jsii.tests.calculator.DerivedStruct.class;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ClassWithDocs.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ClassWithDocs.java
index 49ccc00648..3c32021c18 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ClassWithDocs.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ClassWithDocs.java
@@ -11,7 +11,6 @@
  * }
  * 
  * @see https://aws.amazon.com/
- * @deprecated Use something else please
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
 @software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.ClassWithDocs")
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
new file mode 100644
index 0000000000..8a63ce956d
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
@@ -0,0 +1,65 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ * This tests code generation of deprecation markers.
+ * 
+ * @deprecated without replacement
+ */
+@Deprecated
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.DeprecatedClass")
+public class DeprecatedClass extends software.amazon.jsii.JsiiObject {
+    protected DeprecatedClass(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+        super(mode);
+    }
+    /**
+     * @deprecated this is unsafe
+     * @param argument some string.
+     */
+    @Deprecated
+    public DeprecatedClass(@javax.annotation.Nullable final java.lang.String argument) {
+        super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
+        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { argument });
+    }
+    /**
+     * @deprecated this is unsafe
+     */
+    @Deprecated
+    public DeprecatedClass() {
+        super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
+        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this);
+    }
+
+    /**
+     * @deprecated throws unexpected errors
+     */
+    @Deprecated
+    public void deprecatedMethod() {
+        this.jsiiCall("deprecatedMethod", Void.class);
+    }
+
+    /**
+     * @deprecated intentionally
+     */
+    @Deprecated
+    public java.lang.String getDeprecatedAttribute() {
+        return this.jsiiGet("deprecatedAttribute", java.lang.String.class);
+    }
+
+    /**
+     * @deprecated can be unexpectedly non-null!
+     */
+    @Deprecated
+    @javax.annotation.Nullable
+    protected java.lang.String getDeprecatedProtected() {
+        return this.jsiiGet("deprecatedProtected", java.lang.String.class);
+    }
+
+    /**
+     * @deprecated can be unexpectedly non-null!
+     */
+    @Deprecated
+    protected void setDeprecatedProtected(@javax.annotation.Nullable final java.lang.String value) {
+        this.jsiiSet("deprecatedProtected", value);
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Old.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Old.java
index 5d3a042dc0..a671e98a0a 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Old.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Old.java
@@ -5,6 +5,7 @@
  * 
  * @deprecated Use the new class
  */
+@Deprecated
 @javax.annotation.Generated(value = "jsii-pacmak")
 @software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.Old")
 public class Old extends software.amazon.jsii.JsiiObject {
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py b/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
index d2d53fec76..04f162b948 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
@@ -424,9 +424,6 @@ class ClassWithDocs(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.ClassWithDocs"
 
     The docs are great. They're a bunch of tags.
 
-    Deprecated:
-        Use something else please
-
     See:
         https://aws.amazon.com/
     customAttribute:
@@ -550,6 +547,53 @@ def arg2(self) -> typing.Optional[str]:
         return jsii.get(self, "arg2")
 
 
+class DeprecatedClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.DeprecatedClass"):
+    """This tests code generation of deprecation markers.
+
+    Deprecated:
+        without replacement
+    """
+    def __init__(self, argument: typing.Optional[str]=None) -> None:
+        """
+        Arguments:
+            argument: some string.
+
+        Deprecated:
+            this is unsafe
+        """
+        jsii.create(DeprecatedClass, self, [argument])
+
+    @jsii.member(jsii_name="deprecatedMethod")
+    def deprecated_method(self) -> None:
+        """
+        Deprecated:
+            throws unexpected errors
+        """
+        return jsii.invoke(self, "deprecatedMethod", [])
+
+    @property
+    @jsii.member(jsii_name="deprecatedAttribute")
+    def deprecated_attribute(self) -> str:
+        """
+        Deprecated:
+            intentionally
+        """
+        return jsii.get(self, "deprecatedAttribute")
+
+    @property
+    @jsii.member(jsii_name="deprecatedProtected")
+    def _deprecated_protected(self) -> typing.Optional[str]:
+        """
+        Deprecated:
+            can be unexpectedly non-null!
+        """
+        return jsii.get(self, "deprecatedProtected")
+
+    @_deprecated_protected.setter
+    def _deprecated_protected(self, value: typing.Optional[str]):
+        return jsii.set(self, "deprecatedProtected", value)
+
+
 class DerivedClassHasNoProperties:
     class Base(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.DerivedClassHasNoProperties.Base"):
         def __init__(self) -> None:
@@ -3320,6 +3364,6 @@ def parts(self, value: typing.List[scope.jsii_calc_lib.Value]):
         return jsii.set(self, "parts", value)
 
 
-__all__ = ["AbstractClass", "AbstractClassBase", "AbstractClassReturner", "Add", "AllTypes", "AllTypesEnum", "AllowedMethodNames", "AsyncVirtualMethods", "AugmentableClass", "BinaryOperation", "Calculator", "CalculatorProps", "ClassThatImplementsTheInternalInterface", "ClassThatImplementsThePrivateInterface", "ClassWithDocs", "ClassWithMutableObjectLiteralProperty", "ClassWithPrivateConstructorAndAutomaticProperties", "ConstructorPassesThisOut", "Constructors", "ConsumersOfThisCrazyTypeSystem", "DefaultedConstructorArgument", "DerivedClassHasNoProperties", "DerivedStruct", "DoNotOverridePrivates", "DoNotRecognizeAnyAsOptional", "DocumentedClass", "DontComplainAboutVariadicAfterOptional", "DoubleTrouble", "EraseUndefinedHashValues", "EraseUndefinedHashValuesOptions", "ExportedBaseClass", "ExtendsInternalInterface", "GiveMeStructs", "Greetee", "GreetingAugmenter", "IAnotherPublicInterface", "IExtendsPrivateInterface", "IFriendlier", "IFriendlyRandomGenerator", "IInterfaceImplementedByAbstractClass", "IInterfaceThatShouldNotBeADataType", "IInterfaceWithInternal", "IInterfaceWithMethods", "IInterfaceWithOptionalMethodArguments", "IInterfaceWithProperties", "IInterfaceWithPropertiesExtension", "IJSII417Derived", "IJSII417PublicBaseOfBase", "IJsii487External", "IJsii487External2", "IJsii496", "IMutableObjectLiteral", "INonInternalInterface", "IPrivatelyImplemented", "IPublicInterface", "IPublicInterface2", "IRandomNumberGenerator", "IReturnsNumber", "ImplementInternalInterface", "ImplementsInterfaceWithInternal", "ImplementsInterfaceWithInternalSubclass", "ImplementsPrivateInterface", "ImplictBaseOfBase", "InbetweenClass", "InterfaceInNamespaceIncludesClasses", "InterfaceInNamespaceOnlyInterface", "JSII417Derived", "JSII417PublicBaseOfBase", "JSObjectLiteralForInterface", "JSObjectLiteralToNative", "JSObjectLiteralToNativeClass", "JavaReservedWords", "Jsii487Derived", "Jsii496Derived", "JsiiAgent", "LoadBalancedFargateServiceProps", "Multiply", "Negate", "NodeStandardLibrary", "NullShouldBeTreatedAsUndefined", "NullShouldBeTreatedAsUndefinedData", "NumberGenerator", "ObjectRefsInCollections", "Old", "OptionalConstructorArgument", "OptionalStruct", "OptionalStructConsumer", "OverrideReturnsObject", "PartiallyInitializedThisConsumer", "Polymorphism", "Power", "PublicClass", "PythonReservedWords", "ReferenceEnumFromScopedPackage", "ReturnsPrivateImplementationOfInterface", "RuntimeTypeChecking", "SingleInstanceTwoTypes", "StaticContext", "Statics", "StringEnum", "StripInternal", "Sum", "SyncVirtualMethods", "Thrower", "UnaryOperation", "UnionProperties", "UseBundledDependency", "UseCalcBase", "UsesInterfaceWithProperties", "VariadicMethod", "VirtualMethodPlayground", "VoidCallback", "__jsii_assembly__", "composition"]
+__all__ = ["AbstractClass", "AbstractClassBase", "AbstractClassReturner", "Add", "AllTypes", "AllTypesEnum", "AllowedMethodNames", "AsyncVirtualMethods", "AugmentableClass", "BinaryOperation", "Calculator", "CalculatorProps", "ClassThatImplementsTheInternalInterface", "ClassThatImplementsThePrivateInterface", "ClassWithDocs", "ClassWithMutableObjectLiteralProperty", "ClassWithPrivateConstructorAndAutomaticProperties", "ConstructorPassesThisOut", "Constructors", "ConsumersOfThisCrazyTypeSystem", "DefaultedConstructorArgument", "DeprecatedClass", "DerivedClassHasNoProperties", "DerivedStruct", "DoNotOverridePrivates", "DoNotRecognizeAnyAsOptional", "DocumentedClass", "DontComplainAboutVariadicAfterOptional", "DoubleTrouble", "EraseUndefinedHashValues", "EraseUndefinedHashValuesOptions", "ExportedBaseClass", "ExtendsInternalInterface", "GiveMeStructs", "Greetee", "GreetingAugmenter", "IAnotherPublicInterface", "IExtendsPrivateInterface", "IFriendlier", "IFriendlyRandomGenerator", "IInterfaceImplementedByAbstractClass", "IInterfaceThatShouldNotBeADataType", "IInterfaceWithInternal", "IInterfaceWithMethods", "IInterfaceWithOptionalMethodArguments", "IInterfaceWithProperties", "IInterfaceWithPropertiesExtension", "IJSII417Derived", "IJSII417PublicBaseOfBase", "IJsii487External", "IJsii487External2", "IJsii496", "IMutableObjectLiteral", "INonInternalInterface", "IPrivatelyImplemented", "IPublicInterface", "IPublicInterface2", "IRandomNumberGenerator", "IReturnsNumber", "ImplementInternalInterface", "ImplementsInterfaceWithInternal", "ImplementsInterfaceWithInternalSubclass", "ImplementsPrivateInterface", "ImplictBaseOfBase", "InbetweenClass", "InterfaceInNamespaceIncludesClasses", "InterfaceInNamespaceOnlyInterface", "JSII417Derived", "JSII417PublicBaseOfBase", "JSObjectLiteralForInterface", "JSObjectLiteralToNative", "JSObjectLiteralToNativeClass", "JavaReservedWords", "Jsii487Derived", "Jsii496Derived", "JsiiAgent", "LoadBalancedFargateServiceProps", "Multiply", "Negate", "NodeStandardLibrary", "NullShouldBeTreatedAsUndefined", "NullShouldBeTreatedAsUndefinedData", "NumberGenerator", "ObjectRefsInCollections", "Old", "OptionalConstructorArgument", "OptionalStruct", "OptionalStructConsumer", "OverrideReturnsObject", "PartiallyInitializedThisConsumer", "Polymorphism", "Power", "PublicClass", "PythonReservedWords", "ReferenceEnumFromScopedPackage", "ReturnsPrivateImplementationOfInterface", "RuntimeTypeChecking", "SingleInstanceTwoTypes", "StaticContext", "Statics", "StringEnum", "StripInternal", "Sum", "SyncVirtualMethods", "Thrower", "UnaryOperation", "UnionProperties", "UseBundledDependency", "UseCalcBase", "UsesInterfaceWithProperties", "VariadicMethod", "VirtualMethodPlayground", "VoidCallback", "__jsii_assembly__", "composition"]
 
 publication.publish()
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
index 607b034b60..620f5a6fca 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
@@ -1489,6 +1489,56 @@ DefaultedConstructorArgument
       :type: string *(optional)* *(readonly)*
 
 
+DeprecatedClass
+^^^^^^^^^^^^^^^
+
+.. py:class:: DeprecatedClass([argument])
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.DeprecatedClass;
+
+      .. code-tab:: javascript
+
+         const { DeprecatedClass } = require('jsii-calc');
+
+      .. code-tab:: typescript
+
+         import { DeprecatedClass } from 'jsii-calc';
+
+
+
+   This tests code generation of deprecation markers.
+
+
+
+   :param argument: some string.
+   :type argument: string
+
+   .. py:method:: deprecatedMethod()
+
+
+
+   .. py:attribute:: deprecatedAttribute
+
+      :type: string *(readonly)*
+
+
+   .. py:attribute:: deprecatedProtected
+
+      *Protected property*
+
+      :type: string *(optional)*
+
+
 
 DerivedClassHasNoProperties
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/packages/jsii-spec/lib/spec.ts b/packages/jsii-spec/lib/spec.ts
index d47bba6f48..8d1e3dde67 100644
--- a/packages/jsii-spec/lib/spec.ts
+++ b/packages/jsii-spec/lib/spec.ts
@@ -911,3 +911,14 @@ export function describeTypeReference(type?: TypeReference): string {
 
     throw new Error('Unrecognized type reference');
 }
+
+/**
+ * Determines whether an entity is deprecated.
+ *
+ * @param entity the entity to be checked.
+ *
+ * @returns true if the entity is marked as deprecated.
+ */
+export function isDeprecated(entity: Documentable): boolean {
+    return entity.docs != null && entity.docs.stability === Stability.Deprecated;
+}
diff --git a/packages/jsii/lib/docs.ts b/packages/jsii/lib/docs.ts
index b775bf2422..ed4f977884 100644
--- a/packages/jsii/lib/docs.ts
+++ b/packages/jsii/lib/docs.ts
@@ -101,12 +101,21 @@ function parseDocParts(comments: string | undefined, tags: ts.JSDocTagInfo[]): D
     diagnostics.push('Element is marked both @experimental and @stable.');
   }
 
-  if (docs.deprecated !== undefined && docs.deprecated.trim() === '') {
-    diagnostics.push('@deprecated tag needs a reason and/or suggested alternatives.');
+  if (docs.deprecated !== undefined) {
+    if (docs.deprecated.trim() === '') {
+      diagnostics.push('@deprecated tag needs a reason and/or suggested alternatives.');
+    }
+    if (stable) {
+      diagnostics.push('Element is marked both @deprecated and @stable.');
+    }
+    if (experimental) {
+      diagnostics.push('Element is marked both @deprecated and @experimental.');
+    }
   }
 
   if (experimental) { docs.stability = spec.Stability.Experimental; }
   if (stable) { docs.stability = spec.Stability.Stable; }
+  if (docs.deprecated) { docs.stability = spec.Stability.Deprecated; }
 
   if (tagNames.size > 0) {
     docs.custom = {};

From e911fc439facb23625fa936a0db57699837dadf8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Tue, 4 Jun 2019 16:52:01 +0200
Subject: [PATCH 5/9] Fix broken test expectations

---
 packages/jsii-reflect/test/classes.expected.txt    |  1 +
 .../test/jsii-tree.test.all.expected.txt           | 14 ++++++++++++++
 .../test/jsii-tree.test.inheritance.expected.txt   |  1 +
 .../test/jsii-tree.test.members.expected.txt       |  6 ++++++
 .../test/jsii-tree.test.types.expected.txt         |  1 +
 5 files changed, 23 insertions(+)

diff --git a/packages/jsii-reflect/test/classes.expected.txt b/packages/jsii-reflect/test/classes.expected.txt
index 11f35d759f..6345821969 100644
--- a/packages/jsii-reflect/test/classes.expected.txt
+++ b/packages/jsii-reflect/test/classes.expected.txt
@@ -20,6 +20,7 @@ ConstructorPassesThisOut
 Constructors
 ConsumersOfThisCrazyTypeSystem
 DefaultedConstructorArgument
+DeprecatedClass
 Derived
 DoNotOverridePrivates
 DoNotRecognizeAnyAsOptional
diff --git a/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
index 1ba0d6f468..23ece48499 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
@@ -331,6 +331,20 @@ assemblies
  │   │   └─┬ arg2 property
  │   │     ├── immutable
  │   │     └── type: Optional<string>
+ │   ├─┬ class DeprecatedClass
+ │   │ └─┬ members
+ │   │   ├─┬ <initializer>(argument) initializer
+ │   │   │ └─┬ parameters
+ │   │   │   └─┬ argument
+ │   │   │     └── type: Optional<string>
+ │   │   ├─┬ deprecatedMethod() method
+ │   │   │ └── returns: void
+ │   │   ├─┬ deprecatedAttribute property
+ │   │   │ ├── immutable
+ │   │   │ └── type: string
+ │   │   └─┬ deprecatedProtected property
+ │   │     ├── protected
+ │   │     └── type: Optional<string>
  │   ├─┬ class Base
  │   │ └─┬ members
  │   │   ├── <initializer>() initializer
diff --git a/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
index 27972a66b8..a0d65943e1 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
@@ -29,6 +29,7 @@ assemblies
  │   ├── class Constructors
  │   ├── class ConsumersOfThisCrazyTypeSystem
  │   ├── class DefaultedConstructorArgument
+ │   ├── class DeprecatedClass
  │   ├── class Base
  │   ├─┬ class Derived
  │   │ └── base: Base
diff --git a/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
index 004b4a2fff..2dcc27ed9d 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
@@ -138,6 +138,12 @@ assemblies
  │   │   ├── arg1 property
  │   │   ├── arg3 property
  │   │   └── arg2 property
+ │   ├─┬ class DeprecatedClass
+ │   │ └─┬ members
+ │   │   ├── <initializer>(argument) initializer
+ │   │   ├── deprecatedMethod() method
+ │   │   ├── deprecatedAttribute property
+ │   │   └── deprecatedProtected property
  │   ├─┬ class Base
  │   │ └─┬ members
  │   │   ├── <initializer>() initializer
diff --git a/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
index 3c4c10f766..b7f4ca7269 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
@@ -20,6 +20,7 @@ assemblies
  │   ├── class Constructors
  │   ├── class ConsumersOfThisCrazyTypeSystem
  │   ├── class DefaultedConstructorArgument
+ │   ├── class DeprecatedClass
  │   ├── class Base
  │   ├── class Derived
  │   ├── class DoNotOverridePrivates

From 7f134b53781bbdaf33124ab5c53cc3e8c00b5ab1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Wed, 5 Jun 2019 11:04:09 +0200
Subject: [PATCH 6/9] More PR feedback

---
 packages/jsii-calc-lib/package.json           |  4 +-
 packages/jsii-calc-lib/test/assembly.jsii     |  6 ++-
 packages/jsii-calc/lib/compliance.ts          | 13 +++++
 packages/jsii-calc/test/assembly.jsii         | 37 +++++++++++++-
 .../java/software/amazon/jsii/Stability.java  | 45 ++++++++++++++++
 packages/jsii-pacmak/lib/targets/java.ts      | 46 ++++++++++++-----
 packages/jsii-pacmak/lib/targets/python.ts    |  2 +-
 .../.jsii                                     |  6 ++-
 .../tests/calculator/lib/package-info.java    |  7 +++
 .../.jsii                                     | 37 +++++++++++++-
 .../CalculatorNamespace/StabilityTest.cs      | 23 +++++++++
 .../amazon/jsii/tests/calculator/$Module.java |  1 +
 .../jsii/tests/calculator/ClassWithDocs.java  |  1 +
 .../tests/calculator/DeprecatedClass.java     |  9 +++-
 .../tests/calculator/DocumentedClass.java     |  2 +
 .../amazon/jsii/tests/calculator/Old.java     |  3 +-
 .../jsii/tests/calculator/StabilityTest.java  | 25 +++++++++
 .../jsii/tests/calculator/package-info.java   |  3 +-
 .../python/src/jsii_calc/__init__.py          | 51 ++++++++++++++++++-
 .../expected.jsii-calc/sphinx/jsii-calc.rst   | 38 ++++++++++++++
 .../test/jsii-tree.test.all.expected.txt      |  4 ++
 .../jsii-tree.test.inheritance.expected.txt   |  1 +
 .../test/jsii-tree.test.members.expected.txt  |  4 ++
 .../test/jsii-tree.test.types.expected.txt    |  1 +
 24 files changed, 345 insertions(+), 24 deletions(-)
 create mode 100644 packages/jsii-java-runtime/project/src/main/java/software/amazon/jsii/Stability.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/package-info.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StabilityTest.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StabilityTest.java

diff --git a/packages/jsii-calc-lib/package.json b/packages/jsii-calc-lib/package.json
index 7123f9bc9d..a4079c9736 100644
--- a/packages/jsii-calc-lib/package.json
+++ b/packages/jsii-calc-lib/package.json
@@ -2,6 +2,8 @@
   "name": "@scope/jsii-calc-lib",
   "version": "0.11.0",
   "description": "A simple calcuator library built on JSII.",
+  "stability": "deprecated",
+  "deprecated": "Really just deprecated for shows...",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "private": true,
@@ -51,4 +53,4 @@
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
   }
-}
\ No newline at end of file
+}
diff --git a/packages/jsii-calc-lib/test/assembly.jsii b/packages/jsii-calc-lib/test/assembly.jsii
index 1616631195..0b3cc71378 100644
--- a/packages/jsii-calc-lib/test/assembly.jsii
+++ b/packages/jsii-calc-lib/test/assembly.jsii
@@ -84,6 +84,10 @@
     }
   },
   "description": "A simple calcuator library built on JSII.",
+  "docs": {
+    "deprecated": "Really just deprecated for shows...",
+    "stability": "deprecated"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -496,5 +500,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "EtAUzTnV+hmz9yrXilnsS0MhQuQ/qmpmbwxvdLu561k="
+  "fingerprint": "x/BbPdAJTYB6QY83ucqo0CNLa2NoLebqPMbMY7BsyR4="
 }
diff --git a/packages/jsii-calc/lib/compliance.ts b/packages/jsii-calc/lib/compliance.ts
index 016fcf559c..ac22e67958 100644
--- a/packages/jsii-calc/lib/compliance.ts
+++ b/packages/jsii-calc/lib/compliance.ts
@@ -1713,3 +1713,16 @@ export class DeprecatedClass {
         throw new Error();
     }
 }
+/**
+ * This enum is there to test various stability levels are correctly emitted.
+ *
+ * @stable
+ */
+export enum StabilityTest {
+    /** @deprecated yeah this one's no good */
+    DeprecatedMember,
+    /** @experimental */
+    ExperimentalMember,
+    /** @stable */
+    StableMember
+}
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
index c51241fdb4..4403c079d7 100644
--- a/packages/jsii-calc/test/assembly.jsii
+++ b/packages/jsii-calc/test/assembly.jsii
@@ -5745,6 +5745,41 @@
       ],
       "name": "SingleInstanceTwoTypes"
     },
+    "jsii-calc.StabilityTest": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "stable",
+        "summary": "This enum is there to test various stability levels are correctly emitted."
+      },
+      "fqn": "jsii-calc.StabilityTest",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 1721
+      },
+      "members": [
+        {
+          "docs": {
+            "deprecated": "yeah this one's no good",
+            "stability": "deprecated"
+          },
+          "name": "DeprecatedMember"
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "name": "ExperimentalMember"
+        },
+        {
+          "docs": {
+            "stability": "stable"
+          },
+          "name": "StableMember"
+        }
+      ],
+      "name": "StabilityTest"
+    },
     "jsii-calc.StaticContext": {
       "assembly": "jsii-calc",
       "docs": {
@@ -6892,5 +6927,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "5R2rpEqEYZnuiNa8EnVDEierWuf4xkcuVJDj4a7hNPk="
+  "fingerprint": "UHwu7qd5MqRQCz8lxX6GriJru8ZUKZRu1Oi7QZ3zDnM="
 }
diff --git a/packages/jsii-java-runtime/project/src/main/java/software/amazon/jsii/Stability.java b/packages/jsii-java-runtime/project/src/main/java/software/amazon/jsii/Stability.java
new file mode 100644
index 0000000000..22f5f623d9
--- /dev/null
+++ b/packages/jsii-java-runtime/project/src/main/java/software/amazon/jsii/Stability.java
@@ -0,0 +1,45 @@
+package software.amazon.jsii;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Documents the stability of an API.
+ */
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD, ElementType.PACKAGE, ElementType.TYPE})
+public @interface Stability {
+  /**
+   * @return The stability level of the annotated API.
+   */
+  Level value();
+
+  /**
+   * Stability level of an API, similar to the Node.js stability index.
+   *
+   * @see <a href="https://nodejs.org/api/documentation.html#documentation_stability_index">https://nodejs.org/api/documentation.html#documentation_stability_index</a>
+   */
+  public enum Level {
+    /**
+     * The API is not subject to Semantic Versioning rules. Non-backward compatible changes or removal may occur in any
+     * future release. Use of the API is not recommended in production environments.
+     */
+    Experimental,
+
+    /**
+     * The API is subject to Sematic Versining rules. It may not change in non-backward compatible ways in a subsequent
+     * patch or feature version.
+     */
+    Stable,
+
+    /**
+     * The API may emit warnings. Backward compatibility is not guaranteed. APIs annotated with the {@code Deprecated}
+     * level should also be annotated with the standard {@link Deprecated} annotation.
+     */
+    Deprecated
+  }
+}
diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
index b891c13562..c3a6ee2f6d 100644
--- a/packages/jsii-pacmak/lib/targets/java.ts
+++ b/packages/jsii-pacmak/lib/targets/java.ts
@@ -197,8 +197,8 @@ class JavaGenerator extends Generator {
         const inner = nested ? ' static' : '';
         const absPrefix = abstract ? ' abstract' : '';
 
-        if (spec.isDeprecated(cls)) { this.code.line('@Deprecated'); }
         if (!nested) { this.emitGeneratedAnnotation(); }
+        this.emitStabilityAnnotations(cls);
         this.code.line(`@software.amazon.jsii.Jsii(module = ${this.moduleClass}.class, fqn = "${cls.fqn}")`);
         this.code.openBlock(`public${inner}${absPrefix} class ${cls.name}${extendsExpression}${implementsExpr}`);
 
@@ -217,7 +217,7 @@ class JavaGenerator extends Generator {
 
     protected onInitializer(cls: spec.ClassType, method: spec.Method) {
         this.addJavaDocs(method);
-        if (spec.isDeprecated(method)) { this.code.line('@Deprecated'); }
+        this.emitStabilityAnnotations(method);
         this.code.openBlock(`${this.renderAccessLevel(method)} ${cls.name}(${this.renderMethodParameters(method)})`);
         this.code.line('super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);');
         this.code.line(`software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this${this.renderMethodCallArguments(method)});`);
@@ -275,6 +275,7 @@ class JavaGenerator extends Generator {
         this.openFileIfNeeded(enm);
         this.addJavaDocs(enm);
         if (!this.isNested(enm)) { this.emitGeneratedAnnotation(); }
+        this.emitStabilityAnnotations(enm);
         this.code.line(`@software.amazon.jsii.Jsii(module = ${this.moduleClass}.class, fqn = "${enm.fqn}")`);
         this.code.openBlock(`public enum ${enm.name}`);
     }
@@ -284,6 +285,7 @@ class JavaGenerator extends Generator {
     }
     protected onEnumMember(_: spec.EnumType, member: spec.EnumMember) {
         this.addJavaDocs(member);
+        this.emitStabilityAnnotations(member);
         this.code.line(`${member.name},`);
     }
 
@@ -362,17 +364,14 @@ class JavaGenerator extends Generator {
             for (const line of md2html(mod.readme.markdown).split('\n')) {
                 this.code.line(` * ${line}`);
             }
-            this.code.line(' *');
         }
         if (mod.docs.deprecated) {
-            this.code.line(` * @deprecated ${mod.docs.deprecated}`);
-        } else if (mod.docs.stability) {
-            this.code.line(` * @stability ${mod.docs.stability}`);
+            this.code.line(' *');
+            // Javac won't allow @deprecated on packages, while @Deprecated is aaaabsolutely fine. Duh.
+            this.code.line(` * Deprecated: ${mod.docs.deprecated}`);
         }
         this.code.line(' */');
-        if (mod.docs.deprecated) {
-            this.code.line('@Deprecated');
-        }
+        this.emitStabilityAnnotations(mod);
         this.code.line(`package ${packageName};`);
         this.code.closeFile(packageInfoFile);
     }
@@ -583,7 +582,7 @@ class JavaGenerator extends Generator {
         const access = this.renderAccessLevel(prop);
 
         this.addJavaDocs(prop);
-        if (spec.isDeprecated(prop)) { this.code.line('@Deprecated'); }
+        this.emitStabilityAnnotations(prop);
         this.code.line(`${access} final static ${propType} ${propName};`);
     }
 
@@ -601,7 +600,7 @@ class JavaGenerator extends Generator {
             this.code.line();
             this.addJavaDocs(prop);
             if (overrides) { this.code.line('@Override'); }
-            if (spec.isDeprecated(prop)) { this.code.line('@Deprecated'); }
+            this.emitStabilityAnnotations(prop);
             if (isNullable(prop)) { this.code.line(JSR305_NULLABLE); }
             this.code.openBlock(`${access} ${statc}${getterType} get${propName}()`);
 
@@ -623,7 +622,7 @@ class JavaGenerator extends Generator {
                 this.code.line();
                 this.addJavaDocs(prop);
                 if (overrides) { this.code.line('@Override'); }
-                if (spec.isDeprecated(prop)) { this.code.line('@Deprecated'); }
+                this.emitStabilityAnnotations(prop);
                 const nullable = isNullable(prop) ? `${JSR305_NULLABLE} ` : '';
                 this.code.openBlock(`${access} ${statc}void set${propName}(${nullable}final ${type} value)`);
                 let statement = '';
@@ -650,7 +649,7 @@ class JavaGenerator extends Generator {
         const signature = `${returnType} ${methodName}(${this.renderMethodParameters(method)})`;
         this.code.line();
         this.addJavaDocs(method);
-        if (spec.isDeprecated(method)) { this.code.line('@Deprecated'); }
+        this.emitStabilityAnnotations(method);
         if (overrides) { this.code.line('@Override'); }
         if (isNullable(method.returns)) { this.code.line(JSR305_NULLABLE); }
         if (method.abstract) {
@@ -736,6 +735,27 @@ class JavaGenerator extends Generator {
         this.code.closeBlock();
     }
 
+    private emitStabilityAnnotations(entity: spec.Documentable) {
+        if (!entity.docs) { return; }
+        if (entity.docs.stability === spec.Stability.Deprecated || entity.docs.deprecated) {
+            this.code.line('@Deprecated');
+        }
+        if (entity.docs.stability) {
+            this.code.line(`@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.${_level(entity.docs.stability)})`);
+        }
+
+        function _level(stability: spec.Stability): string {
+            switch (stability) {
+                case spec.Stability.Deprecated:
+                    return 'Deprecated';
+                case spec.Stability.Experimental:
+                    return 'Experimental';
+                case spec.Stability.Stable:
+                    return 'Stable';
+            }
+        }
+    }
+
     private emitInterfaceBuilder(ifc: spec.InterfaceType) {
         const interfaceName = ifc.name;
         const builderName = 'Builder';
diff --git a/packages/jsii-pacmak/lib/targets/python.ts b/packages/jsii-pacmak/lib/targets/python.ts
index 87879f92c4..2c515851ee 100644
--- a/packages/jsii-pacmak/lib/targets/python.ts
+++ b/packages/jsii-pacmak/lib/targets/python.ts
@@ -1778,7 +1778,7 @@ function emitDocString(code: CodeMaker, docs: spec.Docs | undefined, options: {
     if (docs.returns) { block('Returns:', docs.returns); }
     if (docs.deprecated) { block('Deprecated:', docs.deprecated); }
     if (docs.see) { block('See:', docs.see, false); }
-    if (docs.stability === spec.Stability.Experimental) { block('Stability:', docs.stability, false); }
+    if (docs.stability) { block('Stability:', docs.stability, false); }
     if (docs.subclassable) { block('Subclassable:', 'Yes'); }
 
     for (const [k, v] of Object.entries(docs.custom || {})) {
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/.jsii
index 1616631195..0b3cc71378 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/.jsii
+++ b/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/.jsii
@@ -84,6 +84,10 @@
     }
   },
   "description": "A simple calcuator library built on JSII.",
+  "docs": {
+    "deprecated": "Really just deprecated for shows...",
+    "stability": "deprecated"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -496,5 +500,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "EtAUzTnV+hmz9yrXilnsS0MhQuQ/qmpmbwxvdLu561k="
+  "fingerprint": "x/BbPdAJTYB6QY83ucqo0CNLa2NoLebqPMbMY7BsyR4="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/package-info.java b/packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/package-info.java
new file mode 100644
index 0000000000..83cb56c7f0
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/package-info.java
@@ -0,0 +1,7 @@
+/**
+ *
+ * Deprecated: Really just deprecated for shows...
+ */
+@Deprecated
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+package software.amazon.jsii.tests.calculator.lib;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
index c51241fdb4..4403c079d7 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
@@ -5745,6 +5745,41 @@
       ],
       "name": "SingleInstanceTwoTypes"
     },
+    "jsii-calc.StabilityTest": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "stable",
+        "summary": "This enum is there to test various stability levels are correctly emitted."
+      },
+      "fqn": "jsii-calc.StabilityTest",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 1721
+      },
+      "members": [
+        {
+          "docs": {
+            "deprecated": "yeah this one's no good",
+            "stability": "deprecated"
+          },
+          "name": "DeprecatedMember"
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "name": "ExperimentalMember"
+        },
+        {
+          "docs": {
+            "stability": "stable"
+          },
+          "name": "StableMember"
+        }
+      ],
+      "name": "StabilityTest"
+    },
     "jsii-calc.StaticContext": {
       "assembly": "jsii-calc",
       "docs": {
@@ -6892,5 +6927,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "5R2rpEqEYZnuiNa8EnVDEierWuf4xkcuVJDj4a7hNPk="
+  "fingerprint": "UHwu7qd5MqRQCz8lxX6GriJru8ZUKZRu1Oi7QZ3zDnM="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StabilityTest.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StabilityTest.cs
new file mode 100644
index 0000000000..fb94f2d85d
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StabilityTest.cs
@@ -0,0 +1,23 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <summary>This enum is there to test various stability levels are correctly emitted.</summary>
+    /// <remarks>stability: Stable</remarks>
+    [JsiiEnum(nativeType: typeof(StabilityTest), fullyQualifiedName: "jsii-calc.StabilityTest")]
+    public enum StabilityTest
+    {
+        /// <remarks>
+        /// deprecated: yeah this one's no good
+        /// stability: Deprecated
+        /// </remarks>
+        [JsiiEnumMember(name: "DeprecatedMember")]
+        DeprecatedMember,
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiEnumMember(name: "ExperimentalMember")]
+        ExperimentalMember,
+        /// <remarks>stability: Stable</remarks>
+        [JsiiEnumMember(name: "StableMember")]
+        StableMember
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
index 02c68fab10..52a88d859f 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
@@ -118,6 +118,7 @@ protected Class<?> resolveClass(final String fqn) throws ClassNotFoundException
             case "jsii-calc.ReturnsPrivateImplementationOfInterface": return software.amazon.jsii.tests.calculator.ReturnsPrivateImplementationOfInterface.class;
             case "jsii-calc.RuntimeTypeChecking": return software.amazon.jsii.tests.calculator.RuntimeTypeChecking.class;
             case "jsii-calc.SingleInstanceTwoTypes": return software.amazon.jsii.tests.calculator.SingleInstanceTwoTypes.class;
+            case "jsii-calc.StabilityTest": return software.amazon.jsii.tests.calculator.StabilityTest.class;
             case "jsii-calc.StaticContext": return software.amazon.jsii.tests.calculator.StaticContext.class;
             case "jsii-calc.Statics": return software.amazon.jsii.tests.calculator.Statics.class;
             case "jsii-calc.StringEnum": return software.amazon.jsii.tests.calculator.StringEnum.class;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ClassWithDocs.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ClassWithDocs.java
index 3c32021c18..154b3eef9e 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ClassWithDocs.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ClassWithDocs.java
@@ -13,6 +13,7 @@
  * @see https://aws.amazon.com/
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
 @software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.ClassWithDocs")
 public class ClassWithDocs extends software.amazon.jsii.JsiiObject {
     protected ClassWithDocs(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
index 8a63ce956d..70a05578e5 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
@@ -5,8 +5,9 @@
  * 
  * @deprecated without replacement
  */
-@Deprecated
 @javax.annotation.Generated(value = "jsii-pacmak")
+@Deprecated
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
 @software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.DeprecatedClass")
 public class DeprecatedClass extends software.amazon.jsii.JsiiObject {
     protected DeprecatedClass(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
@@ -17,6 +18,7 @@ protected DeprecatedClass(final software.amazon.jsii.JsiiObject.InitializationMo
      * @param argument some string.
      */
     @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     public DeprecatedClass(@javax.annotation.Nullable final java.lang.String argument) {
         super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
         software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { argument });
@@ -25,6 +27,7 @@ public DeprecatedClass(@javax.annotation.Nullable final java.lang.String argumen
      * @deprecated this is unsafe
      */
     @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     public DeprecatedClass() {
         super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
         software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this);
@@ -34,6 +37,7 @@ public DeprecatedClass() {
      * @deprecated throws unexpected errors
      */
     @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     public void deprecatedMethod() {
         this.jsiiCall("deprecatedMethod", Void.class);
     }
@@ -42,6 +46,7 @@ public void deprecatedMethod() {
      * @deprecated intentionally
      */
     @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     public java.lang.String getDeprecatedAttribute() {
         return this.jsiiGet("deprecatedAttribute", java.lang.String.class);
     }
@@ -50,6 +55,7 @@ public java.lang.String getDeprecatedAttribute() {
      * @deprecated can be unexpectedly non-null!
      */
     @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @javax.annotation.Nullable
     protected java.lang.String getDeprecatedProtected() {
         return this.jsiiGet("deprecatedProtected", java.lang.String.class);
@@ -59,6 +65,7 @@ protected java.lang.String getDeprecatedProtected() {
      * @deprecated can be unexpectedly non-null!
      */
     @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     protected void setDeprecatedProtected(@javax.annotation.Nullable final java.lang.String value) {
         this.jsiiSet("deprecatedProtected", value);
     }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DocumentedClass.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DocumentedClass.java
index 53beff9d07..37051fa214 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DocumentedClass.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DocumentedClass.java
@@ -9,6 +9,7 @@
  * Multiple paragraphs are separated by an empty line.
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
 @software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.DocumentedClass")
 public class DocumentedClass extends software.amazon.jsii.JsiiObject {
     protected DocumentedClass(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
@@ -49,6 +50,7 @@ public java.lang.Number greet() {
      * 
      * EXPERIMENTAL
      */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public void hola() {
         this.jsiiCall("hola", Void.class);
     }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Old.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Old.java
index a671e98a0a..85a4d6fe82 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Old.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Old.java
@@ -5,8 +5,9 @@
  * 
  * @deprecated Use the new class
  */
-@Deprecated
 @javax.annotation.Generated(value = "jsii-pacmak")
+@Deprecated
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
 @software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.Old")
 public class Old extends software.amazon.jsii.JsiiObject {
     protected Old(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StabilityTest.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StabilityTest.java
new file mode 100644
index 0000000000..589f22a11c
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StabilityTest.java
@@ -0,0 +1,25 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ * This enum is there to test various stability levels are correctly emitted.
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+@software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.StabilityTest")
+public enum StabilityTest {
+    /**
+     * @deprecated yeah this one's no good
+     */
+    @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+    DeprecatedMember,
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    ExperimentalMember,
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    StableMember,
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java
index e227975f67..971596537b 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java
@@ -7,7 +7,6 @@
  * heading will be used as the Sphinx topic name. Otherwise, the name of the module
  * (<code>jsii-calc</code>) will be used instead.</p>
  * 
- *
- * @stability experimental
  */
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
 package software.amazon.jsii.tests.calculator;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py b/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
index 04f162b948..f29e2608a6 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
@@ -426,6 +426,8 @@ class ClassWithDocs(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.ClassWithDocs"
 
     See:
         https://aws.amazon.com/
+    Stability:
+        stable
     customAttribute:
         hasAValue
 
@@ -552,6 +554,9 @@ class DeprecatedClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.DeprecatedCl
 
     Deprecated:
         without replacement
+
+    Stability:
+        deprecated
     """
     def __init__(self, argument: typing.Optional[str]=None) -> None:
         """
@@ -560,6 +565,9 @@ def __init__(self, argument: typing.Optional[str]=None) -> None:
 
         Deprecated:
             this is unsafe
+
+        Stability:
+            deprecated
         """
         jsii.create(DeprecatedClass, self, [argument])
 
@@ -568,6 +576,9 @@ def deprecated_method(self) -> None:
         """
         Deprecated:
             throws unexpected errors
+
+        Stability:
+            deprecated
         """
         return jsii.invoke(self, "deprecatedMethod", [])
 
@@ -577,6 +588,9 @@ def deprecated_attribute(self) -> str:
         """
         Deprecated:
             intentionally
+
+        Stability:
+            deprecated
         """
         return jsii.get(self, "deprecatedAttribute")
 
@@ -586,6 +600,9 @@ def _deprecated_protected(self) -> typing.Optional[str]:
         """
         Deprecated:
             can be unexpectedly non-null!
+
+        Stability:
+            deprecated
         """
         return jsii.get(self, "deprecatedProtected")
 
@@ -676,6 +693,9 @@ class DocumentedClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.DocumentedCl
     multiple lines and multiple paragraphs.
 
     Multiple paragraphs are separated by an empty line.
+
+    Stability:
+        stable
     """
     def __init__(self) -> None:
         jsii.create(DocumentedClass, self, [])
@@ -2309,6 +2329,9 @@ class Old(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.Old"):
 
     Deprecated:
         Use the new class
+
+    Stability:
+        deprecated
     """
     def __init__(self) -> None:
         jsii.create(Old, self, [])
@@ -2682,6 +2705,32 @@ def interface2(self) -> "IPublicInterface":
         return jsii.invoke(self, "interface2", [])
 
 
+@jsii.enum(jsii_type="jsii-calc.StabilityTest")
+class StabilityTest(enum.Enum):
+    """This enum is there to test various stability levels are correctly emitted.
+
+    Stability:
+        stable
+    """
+    DeprecatedMember = "DeprecatedMember"
+    """
+    Deprecated:
+        yeah this one's no good
+
+    Stability:
+        deprecated
+    """
+    ExperimentalMember = "ExperimentalMember"
+    """
+    Stability:
+        experimental
+    """
+    StableMember = "StableMember"
+    """
+    Stability:
+        stable
+    """
+
 class StaticContext(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.StaticContext"):
     """This is used to validate the ability to use ``this`` from within a static context.
 
@@ -3364,6 +3413,6 @@ def parts(self, value: typing.List[scope.jsii_calc_lib.Value]):
         return jsii.set(self, "parts", value)
 
 
-__all__ = ["AbstractClass", "AbstractClassBase", "AbstractClassReturner", "Add", "AllTypes", "AllTypesEnum", "AllowedMethodNames", "AsyncVirtualMethods", "AugmentableClass", "BinaryOperation", "Calculator", "CalculatorProps", "ClassThatImplementsTheInternalInterface", "ClassThatImplementsThePrivateInterface", "ClassWithDocs", "ClassWithMutableObjectLiteralProperty", "ClassWithPrivateConstructorAndAutomaticProperties", "ConstructorPassesThisOut", "Constructors", "ConsumersOfThisCrazyTypeSystem", "DefaultedConstructorArgument", "DeprecatedClass", "DerivedClassHasNoProperties", "DerivedStruct", "DoNotOverridePrivates", "DoNotRecognizeAnyAsOptional", "DocumentedClass", "DontComplainAboutVariadicAfterOptional", "DoubleTrouble", "EraseUndefinedHashValues", "EraseUndefinedHashValuesOptions", "ExportedBaseClass", "ExtendsInternalInterface", "GiveMeStructs", "Greetee", "GreetingAugmenter", "IAnotherPublicInterface", "IExtendsPrivateInterface", "IFriendlier", "IFriendlyRandomGenerator", "IInterfaceImplementedByAbstractClass", "IInterfaceThatShouldNotBeADataType", "IInterfaceWithInternal", "IInterfaceWithMethods", "IInterfaceWithOptionalMethodArguments", "IInterfaceWithProperties", "IInterfaceWithPropertiesExtension", "IJSII417Derived", "IJSII417PublicBaseOfBase", "IJsii487External", "IJsii487External2", "IJsii496", "IMutableObjectLiteral", "INonInternalInterface", "IPrivatelyImplemented", "IPublicInterface", "IPublicInterface2", "IRandomNumberGenerator", "IReturnsNumber", "ImplementInternalInterface", "ImplementsInterfaceWithInternal", "ImplementsInterfaceWithInternalSubclass", "ImplementsPrivateInterface", "ImplictBaseOfBase", "InbetweenClass", "InterfaceInNamespaceIncludesClasses", "InterfaceInNamespaceOnlyInterface", "JSII417Derived", "JSII417PublicBaseOfBase", "JSObjectLiteralForInterface", "JSObjectLiteralToNative", "JSObjectLiteralToNativeClass", "JavaReservedWords", "Jsii487Derived", "Jsii496Derived", "JsiiAgent", "LoadBalancedFargateServiceProps", "Multiply", "Negate", "NodeStandardLibrary", "NullShouldBeTreatedAsUndefined", "NullShouldBeTreatedAsUndefinedData", "NumberGenerator", "ObjectRefsInCollections", "Old", "OptionalConstructorArgument", "OptionalStruct", "OptionalStructConsumer", "OverrideReturnsObject", "PartiallyInitializedThisConsumer", "Polymorphism", "Power", "PublicClass", "PythonReservedWords", "ReferenceEnumFromScopedPackage", "ReturnsPrivateImplementationOfInterface", "RuntimeTypeChecking", "SingleInstanceTwoTypes", "StaticContext", "Statics", "StringEnum", "StripInternal", "Sum", "SyncVirtualMethods", "Thrower", "UnaryOperation", "UnionProperties", "UseBundledDependency", "UseCalcBase", "UsesInterfaceWithProperties", "VariadicMethod", "VirtualMethodPlayground", "VoidCallback", "__jsii_assembly__", "composition"]
+__all__ = ["AbstractClass", "AbstractClassBase", "AbstractClassReturner", "Add", "AllTypes", "AllTypesEnum", "AllowedMethodNames", "AsyncVirtualMethods", "AugmentableClass", "BinaryOperation", "Calculator", "CalculatorProps", "ClassThatImplementsTheInternalInterface", "ClassThatImplementsThePrivateInterface", "ClassWithDocs", "ClassWithMutableObjectLiteralProperty", "ClassWithPrivateConstructorAndAutomaticProperties", "ConstructorPassesThisOut", "Constructors", "ConsumersOfThisCrazyTypeSystem", "DefaultedConstructorArgument", "DeprecatedClass", "DerivedClassHasNoProperties", "DerivedStruct", "DoNotOverridePrivates", "DoNotRecognizeAnyAsOptional", "DocumentedClass", "DontComplainAboutVariadicAfterOptional", "DoubleTrouble", "EraseUndefinedHashValues", "EraseUndefinedHashValuesOptions", "ExportedBaseClass", "ExtendsInternalInterface", "GiveMeStructs", "Greetee", "GreetingAugmenter", "IAnotherPublicInterface", "IExtendsPrivateInterface", "IFriendlier", "IFriendlyRandomGenerator", "IInterfaceImplementedByAbstractClass", "IInterfaceThatShouldNotBeADataType", "IInterfaceWithInternal", "IInterfaceWithMethods", "IInterfaceWithOptionalMethodArguments", "IInterfaceWithProperties", "IInterfaceWithPropertiesExtension", "IJSII417Derived", "IJSII417PublicBaseOfBase", "IJsii487External", "IJsii487External2", "IJsii496", "IMutableObjectLiteral", "INonInternalInterface", "IPrivatelyImplemented", "IPublicInterface", "IPublicInterface2", "IRandomNumberGenerator", "IReturnsNumber", "ImplementInternalInterface", "ImplementsInterfaceWithInternal", "ImplementsInterfaceWithInternalSubclass", "ImplementsPrivateInterface", "ImplictBaseOfBase", "InbetweenClass", "InterfaceInNamespaceIncludesClasses", "InterfaceInNamespaceOnlyInterface", "JSII417Derived", "JSII417PublicBaseOfBase", "JSObjectLiteralForInterface", "JSObjectLiteralToNative", "JSObjectLiteralToNativeClass", "JavaReservedWords", "Jsii487Derived", "Jsii496Derived", "JsiiAgent", "LoadBalancedFargateServiceProps", "Multiply", "Negate", "NodeStandardLibrary", "NullShouldBeTreatedAsUndefined", "NullShouldBeTreatedAsUndefinedData", "NumberGenerator", "ObjectRefsInCollections", "Old", "OptionalConstructorArgument", "OptionalStruct", "OptionalStructConsumer", "OverrideReturnsObject", "PartiallyInitializedThisConsumer", "Polymorphism", "Power", "PublicClass", "PythonReservedWords", "ReferenceEnumFromScopedPackage", "ReturnsPrivateImplementationOfInterface", "RuntimeTypeChecking", "SingleInstanceTwoTypes", "StabilityTest", "StaticContext", "Statics", "StringEnum", "StripInternal", "Sum", "SyncVirtualMethods", "Thrower", "UnaryOperation", "UnionProperties", "UseBundledDependency", "UseCalcBase", "UsesInterfaceWithProperties", "VariadicMethod", "VirtualMethodPlayground", "VoidCallback", "__jsii_assembly__", "composition"]
 
 publication.publish()
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
index 620f5a6fca..3d1b07a0cb 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
@@ -5540,6 +5540,44 @@ SingleInstanceTwoTypes
       :rtype: :py:class:`~jsii-calc.IPublicInterface`\ 
 
 
+StabilityTest (enum)
+^^^^^^^^^^^^^^^^^^^^
+
+.. py:class:: StabilityTest
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.StabilityTest;
+
+      .. code-tab:: javascript
+
+         const { StabilityTest } = require('jsii-calc');
+
+      .. code-tab:: typescript
+
+         import { StabilityTest } from 'jsii-calc';
+
+
+
+   This enum is there to test various stability levels are correctly emitted.
+
+
+
+   .. py:data:: DeprecatedMember
+
+   .. py:data:: ExperimentalMember
+
+   .. py:data:: StableMember
+
+
 StaticContext
 ^^^^^^^^^^^^^
 
diff --git a/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
index 23ece48499..ca5814f53c 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
@@ -1500,6 +1500,10 @@ assemblies
  │   │ ├── MyEnumValue
  │   │ ├── YourEnumValue
  │   │ └── ThisIsGreat
+ │   ├─┬ enum StabilityTest
+ │   │ ├── DeprecatedMember
+ │   │ ├── ExperimentalMember
+ │   │ └── StableMember
  │   ├─┬ enum StringEnum
  │   │ ├── A
  │   │ ├── B
diff --git a/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
index a0d65943e1..bc977cb445 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
@@ -159,6 +159,7 @@ assemblies
  │   ├── interface OptionalStruct
  │   ├── interface UnionProperties
  │   ├── enum AllTypesEnum
+ │   ├── enum StabilityTest
  │   ├── enum StringEnum
  │   └── enum CompositionStringStyle
  ├─┬ @scope/jsii-calc-base
diff --git a/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
index 2dcc27ed9d..4f7d652a22 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
@@ -667,6 +667,10 @@ assemblies
  │   │ ├── MyEnumValue
  │   │ ├── YourEnumValue
  │   │ └── ThisIsGreat
+ │   ├─┬ enum StabilityTest
+ │   │ ├── DeprecatedMember
+ │   │ ├── ExperimentalMember
+ │   │ └── StableMember
  │   ├─┬ enum StringEnum
  │   │ ├── A
  │   │ ├── B
diff --git a/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
index b7f4ca7269..5546e9ed4d 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
@@ -116,6 +116,7 @@ assemblies
  │   ├── interface OptionalStruct
  │   ├── interface UnionProperties
  │   ├── enum AllTypesEnum
+ │   ├── enum StabilityTest
  │   ├── enum StringEnum
  │   └── enum CompositionStringStyle
  ├─┬ @scope/jsii-calc-base

From 49d5a0a860ef271a89c40ba02c1d846206a51610 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Wed, 5 Jun 2019 12:53:05 +0200
Subject: [PATCH 7/9] Add tagging to assembly description

---
 .../src/Amazon.JSII.Generator/AssemblyExtensions.cs  | 12 +++++++++++-
 ...SII.Tests.CalculatorPackageId.LibPackageId.csproj |  2 +-
 .../Amazon.JSII.Tests.CalculatorPackageId.csproj     |  2 +-
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/AssemblyExtensions.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/AssemblyExtensions.cs
index ab780a6ca6..eaac8b5cc5 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/AssemblyExtensions.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/AssemblyExtensions.cs
@@ -61,7 +61,7 @@ public static IEnumerable<XElement> GetMsBuildProperties(this Assembly assembly)
             yield return new XElement("IncludeSource", true);
             yield return new XElement("PackageVersion", assembly.Version);
             yield return new XElement("PackageId", assembly.Targets.DotNet.PackageId);
-            yield return new XElement("Description", assembly.Description);
+            yield return new XElement("Description", GetDescription());
             yield return new XElement("ProjectUrl", assembly.Homepage);
             yield return new XElement("LicenseUrl", $"https://spdx.org/licenses/{assembly.License}.html");
             yield return new XElement("Authors", $"{assembly.Author.Name}");
@@ -91,6 +91,16 @@ public static IEnumerable<XElement> GetMsBuildProperties(this Assembly assembly)
             {
                 yield return new XElement("IconUrl", assembly.Targets.DotNet.IconUrl);
             }
+
+            string GetDescription()
+            {
+                Stability? stability = assembly.Docs?.Stability;
+                if (!stability.HasValue)
+                {
+                    return assembly.Description;
+                }
+                return $"{assembly.Description} (Stability: {stability})";
+            }
         }
     }
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId.csproj b/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId.csproj
index fc3c918990..f973e0ad37 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId.csproj
+++ b/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId.csproj
@@ -6,7 +6,7 @@
     <IncludeSource>true</IncludeSource>
     <PackageVersion>0.11.0</PackageVersion>
     <PackageId>Amazon.JSII.Tests.CalculatorPackageId.LibPackageId</PackageId>
-    <Description>A simple calcuator library built on JSII.</Description>
+    <Description>A simple calcuator library built on JSII. (Stability: Deprecated)</Description>
     <ProjectUrl>https://github.com/awslabs/jsii.git</ProjectUrl>
     <LicenseUrl>https://spdx.org/licenses/Apache-2.0.html</LicenseUrl>
     <Authors>Amazon Web Services</Authors>
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon.JSII.Tests.CalculatorPackageId.csproj b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon.JSII.Tests.CalculatorPackageId.csproj
index 7f55804c53..d926ed32f5 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon.JSII.Tests.CalculatorPackageId.csproj
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon.JSII.Tests.CalculatorPackageId.csproj
@@ -6,7 +6,7 @@
     <IncludeSource>true</IncludeSource>
     <PackageVersion>0.11.0</PackageVersion>
     <PackageId>Amazon.JSII.Tests.CalculatorPackageId</PackageId>
-    <Description>A simple calcuator built on JSII.</Description>
+    <Description>A simple calcuator built on JSII. (Stability: Experimental)</Description>
     <ProjectUrl>https://github.com/awslabs/jsii.git</ProjectUrl>
     <LicenseUrl>https://spdx.org/licenses/Apache-2.0.html</LicenseUrl>
     <Authors>Amazon Web Services</Authors>

From b860b41e8221b009e72583b0bfdfe0240f25157b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Wed, 5 Jun 2019 14:32:54 +0200
Subject: [PATCH 8/9] More polishing and fixes

---
 packages/jsii-calc/lib/compliance.ts          |  45 --
 packages/jsii-calc/lib/index.ts               |   1 +
 packages/jsii-calc/lib/stability.ts           | 104 ++++
 packages/jsii-calc/test/assembly.jsii         | 507 ++++++++++++++++--
 .../Class/ClassGenerator.cs                   |   4 +-
 .../DocComment/DocCommentGeneratorBase.cs     |   1 -
 .../DocComment/MethodDocCommentGenerator.cs   |   4 +-
 .../Enum/EnumGenerator.cs                     |  29 +-
 .../TypeProxyGeneratorBase.cs                 |  21 +-
 packages/jsii-pacmak/lib/targets/java.ts      |  10 +
 .../LibNamespace/Number.cs                    |   2 +
 .../.jsii                                     | 507 ++++++++++++++++--
 .../JSII/Tests/CalculatorNamespace/Add.cs     |   3 +
 .../CalculatorNamespace/BinaryOperation.cs    |   3 +
 .../Tests/CalculatorNamespace/Calculator.cs   |   2 +
 .../CalculatorNamespace/DeprecatedClass.cs    |  54 +-
 .../CalculatorNamespace/DeprecatedEnum.cs     |  19 +
 .../CalculatorNamespace/DeprecatedStruct.cs   |  18 +
 .../DeprecatedStructProxy.cs                  |  22 +
 .../CalculatorNamespace/ExperimentalClass.cs  |  44 ++
 .../CalculatorNamespace/ExperimentalEnum.cs   |  16 +
 .../CalculatorNamespace/ExperimentalStruct.cs |  17 +
 .../ExperimentalStructProxy.cs                |  20 +
 .../IDeprecatedInterfaceProxy.cs              |  31 ++
 .../CalculatorNamespace/IDeprecatedStruct.cs  |  18 +
 .../IExperimentalInterfaceProxy.cs            |  28 +
 .../IExperimentalStruct.cs                    |  16 +
 .../IIDeprecatedInterface.cs                  |  24 +
 .../IIExperimentalInterface.cs                |  21 +
 .../CalculatorNamespace/IIStableInterface.cs  |  21 +
 .../IStableInterfaceProxy.cs                  |  28 +
 .../CalculatorNamespace/IStableStruct.cs      |  16 +
 .../Tests/CalculatorNamespace/Multiply.cs     |   3 +
 .../JSII/Tests/CalculatorNamespace/Old.cs     |   5 +-
 .../JSII/Tests/CalculatorNamespace/Power.cs   |   3 +
 .../CalculatorNamespace/StabilityTest.cs      |  23 -
 .../Tests/CalculatorNamespace/StableClass.cs  |  44 ++
 .../Tests/CalculatorNamespace/StableEnum.cs   |  16 +
 .../Tests/CalculatorNamespace/StableStruct.cs |  17 +
 .../CalculatorNamespace/StableStructProxy.cs  |  20 +
 .../CalculatorNamespace/VariadicMethod.cs     |   1 +
 .../amazon/jsii/tests/calculator/$Module.java |  12 +-
 .../tests/calculator/DeprecatedClass.java     |  41 +-
 .../jsii/tests/calculator/DeprecatedEnum.java |  23 +
 .../tests/calculator/DeprecatedStruct.java    |  92 ++++
 .../tests/calculator/ExperimentalClass.java   |  62 +++
 ...abilityTest.java => ExperimentalEnum.java} |  21 +-
 .../tests/calculator/ExperimentalStruct.java  |  84 +++
 .../calculator/IDeprecatedInterface.java      |  66 +++
 .../calculator/IExperimentalInterface.java    |  60 +++
 .../tests/calculator/IStableInterface.java    |  53 ++
 .../jsii/tests/calculator/StableClass.java    |  55 ++
 .../jsii/tests/calculator/StableEnum.java     |  17 +
 .../jsii/tests/calculator/StableStruct.java   |  81 +++
 .../python/src/jsii_calc/__init__.py          | 436 +++++++++++++--
 .../expected.jsii-calc/sphinx/jsii-calc.rst   | 405 +++++++++++++-
 .../jsii-reflect/test/classes.expected.txt    |   2 +
 .../test/jsii-tree.test.all.expected.txt      | 102 +++-
 .../jsii-tree.test.inheritance.expected.txt   |  12 +-
 .../test/jsii-tree.test.members.expected.txt  |  54 +-
 .../test/jsii-tree.test.types.expected.txt    |  12 +-
 61 files changed, 3164 insertions(+), 314 deletions(-)
 create mode 100644 packages/jsii-calc/lib/stability.ts
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedEnum.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStruct.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStructProxy.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalClass.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalEnum.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalStruct.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalStructProxy.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedInterfaceProxy.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedStruct.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IExperimentalInterfaceProxy.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IExperimentalStruct.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIDeprecatedInterface.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIExperimentalInterface.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIStableInterface.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IStableInterfaceProxy.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IStableStruct.cs
 delete mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StabilityTest.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableClass.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableEnum.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableStruct.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableStructProxy.cs
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedEnum.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalClass.java
 rename packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/{StabilityTest.java => ExperimentalEnum.java} (51%)
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalStruct.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IDeprecatedInterface.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IExperimentalInterface.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IStableInterface.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableClass.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableEnum.java
 create mode 100644 packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableStruct.java

diff --git a/packages/jsii-calc/lib/compliance.ts b/packages/jsii-calc/lib/compliance.ts
index ac22e67958..7442a7b274 100644
--- a/packages/jsii-calc/lib/compliance.ts
+++ b/packages/jsii-calc/lib/compliance.ts
@@ -1681,48 +1681,3 @@ export abstract class VoidCallback {
     }
     protected abstract overrideMe(): void;
 }
-
-/**
- * This tests code generation of deprecation markers
- *
- * @deprecated without replacement
- */
-export class DeprecatedClass {
-    /**
-     * @deprecated intentionally
-     */
-    public readonly deprecatedAttribute: string;
-
-    /**
-     * @deprecated can be unexpectedly non-null!
-     */
-    protected deprecatedProtected?: string;
-
-    /**
-     * @param argument some string
-     * @deprecated this is unsafe
-     */
-    constructor(argument = 'tombstone!') {
-        this.deprecatedAttribute = argument;
-    }
-
-    /**
-     * @deprecated throws unexpected errors
-     */
-    public deprecatedMethod() {
-        throw new Error();
-    }
-}
-/**
- * This enum is there to test various stability levels are correctly emitted.
- *
- * @stable
- */
-export enum StabilityTest {
-    /** @deprecated yeah this one's no good */
-    DeprecatedMember,
-    /** @experimental */
-    ExperimentalMember,
-    /** @stable */
-    StableMember
-}
diff --git a/packages/jsii-calc/lib/index.ts b/packages/jsii-calc/lib/index.ts
index ff61744495..0b507f6734 100644
--- a/packages/jsii-calc/lib/index.ts
+++ b/packages/jsii-calc/lib/index.ts
@@ -2,3 +2,4 @@ export * from './calculator';
 export * from './compliance';
 export * from './documented';
 export * from './erasures';
+export * from './stability';
diff --git a/packages/jsii-calc/lib/stability.ts b/packages/jsii-calc/lib/stability.ts
new file mode 100644
index 0000000000..e0a3ccbe50
--- /dev/null
+++ b/packages/jsii-calc/lib/stability.ts
@@ -0,0 +1,104 @@
+// The following tests validate emission of stability markers
+
+/** @experimental */
+export interface ExperimentalStruct {
+  /** @experimental */
+  readonly readonlyProperty: string;
+}
+/** @experimental */
+export interface IExperimentalInterface {
+  /** @experimental */
+  mutableProperty?: number;
+  /** @experimental */
+  method(): void;
+}
+/** @experimental */
+export class ExperimentalClass {
+  /** @experimental */
+  public readonly readonlyProperty: string;
+  /** @experimental */
+  public mutableProperty?: number;
+  /** @experimental */
+  constructor(readonlyString: string, mutableNumber?: number) {
+    this.readonlyProperty = readonlyString;
+    this.mutableProperty = mutableNumber;
+  }
+
+  /** @experimental */
+  public method(): void { return; }
+}
+/** @experimental */
+export enum ExperimentalEnum {
+  /** @experimental */
+  OptionA,
+  /** @experimental */
+  OptionB
+}
+
+/** @stable */
+export interface StableStruct {
+  /** @stable */
+  readonly readonlyProperty: string;
+}
+/** @stable */
+export interface IStableInterface {
+  /** @stable */
+  mutableProperty?: number;
+  /** @stable */
+  method(): void;
+}
+/** @stable */
+export class StableClass {
+  /** @stable */
+  public readonly readonlyProperty: string = 'wazoo';
+  /** @stable */
+  public mutableProperty?: number;
+  /** @stable */
+  constructor(readonlyString: string, mutableNumber?: number) {
+    this.readonlyProperty = readonlyString;
+    this.mutableProperty = mutableNumber;
+  }
+  /** @stable */
+  public method(): void { return; }
+}
+/** @stable */
+export enum StableEnum {
+  /** @stable */
+  OptionA,
+  /** @stable */
+  OptionB
+}
+
+/** @deprecated for the show */
+export interface DeprecatedStruct {
+  /** @deprecated for the show */
+  readonly readonlyProperty: string;
+}
+/** @deprecated for the show */
+export interface IDeprecatedInterface {
+  /** @deprecated for the show */
+  mutableProperty?: number;
+  /** @deprecated for the show */
+  method(): void;
+}
+/** @deprecated for the show */
+export class DeprecatedClass {
+  /** @deprecated for the show */
+  public readonly readonlyProperty: string = 'wazoo';
+  /** @deprecated for the show */
+  public mutableProperty?: number;
+  /** @deprecated for the show */
+  constructor(readonlyString: string, mutableNumber?: number) {
+    this.readonlyProperty = readonlyString;
+    this.mutableProperty = mutableNumber;
+  }
+  /** @deprecated for the show */
+  public method(): void { return; }
+}
+/** @deprecated for the show */
+export enum DeprecatedEnum {
+  /** @deprecated for the show */
+  OptionA,
+  /** @deprecated for the show */
+  OptionB
+}
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
index 4403c079d7..a6b8a4027a 100644
--- a/packages/jsii-calc/test/assembly.jsii
+++ b/packages/jsii-calc/test/assembly.jsii
@@ -1892,76 +1892,140 @@
     "jsii-calc.DeprecatedClass": {
       "assembly": "jsii-calc",
       "docs": {
-        "deprecated": "without replacement",
-        "stability": "deprecated",
-        "summary": "This tests code generation of deprecation markers."
+        "deprecated": "for the show",
+        "stability": "deprecated"
       },
       "fqn": "jsii-calc.DeprecatedClass",
       "initializer": {
         "docs": {
-          "deprecated": "this is unsafe",
+          "deprecated": "for the show",
           "stability": "deprecated"
         },
         "parameters": [
           {
-            "docs": {
-              "summary": "some string."
-            },
-            "name": "argument",
-            "optional": true,
+            "name": "readonlyString",
             "type": {
               "primitive": "string"
             }
+          },
+          {
+            "name": "mutableNumber",
+            "optional": true,
+            "type": {
+              "primitive": "number"
+            }
           }
         ]
       },
       "kind": "class",
       "locationInModule": {
-        "filename": "lib/compliance.ts",
-        "line": 1690
+        "filename": "lib/stability.ts",
+        "line": 85
       },
       "methods": [
         {
           "docs": {
-            "deprecated": "throws unexpected errors",
+            "deprecated": "for the show",
             "stability": "deprecated"
           },
           "locationInModule": {
-            "filename": "lib/compliance.ts",
-            "line": 1712
+            "filename": "lib/stability.ts",
+            "line": 96
           },
-          "name": "deprecatedMethod"
+          "name": "method"
         }
       ],
       "name": "DeprecatedClass",
       "properties": [
         {
           "docs": {
-            "deprecated": "intentionally",
+            "deprecated": "for the show",
             "stability": "deprecated"
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "lib/compliance.ts",
-            "line": 1694
+            "filename": "lib/stability.ts",
+            "line": 87
           },
-          "name": "deprecatedAttribute",
+          "name": "readonlyProperty",
           "type": {
             "primitive": "string"
           }
         },
         {
           "docs": {
-            "deprecated": "can be unexpectedly non-null!",
+            "deprecated": "for the show",
             "stability": "deprecated"
           },
           "locationInModule": {
-            "filename": "lib/compliance.ts",
-            "line": 1699
+            "filename": "lib/stability.ts",
+            "line": 89
           },
-          "name": "deprecatedProtected",
+          "name": "mutableProperty",
           "optional": true,
-          "protected": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
+    "jsii-calc.DeprecatedEnum": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "deprecated": "for the show",
+        "stability": "deprecated"
+      },
+      "fqn": "jsii-calc.DeprecatedEnum",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 99
+      },
+      "members": [
+        {
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "name": "OptionA"
+        },
+        {
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "name": "OptionB"
+        }
+      ],
+      "name": "DeprecatedEnum"
+    },
+    "jsii-calc.DeprecatedStruct": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "deprecated": "for the show",
+        "stability": "deprecated"
+      },
+      "fqn": "jsii-calc.DeprecatedStruct",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 73
+      },
+      "name": "DeprecatedStruct",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 75
+          },
+          "name": "readonlyProperty",
           "type": {
             "primitive": "string"
           }
@@ -2475,6 +2539,139 @@
         }
       ]
     },
+    "jsii-calc.ExperimentalClass": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "jsii-calc.ExperimentalClass",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        },
+        "parameters": [
+          {
+            "name": "readonlyString",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "mutableNumber",
+            "optional": true,
+            "type": {
+              "primitive": "number"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 16
+      },
+      "methods": [
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 28
+          },
+          "name": "method"
+        }
+      ],
+      "name": "ExperimentalClass",
+      "properties": [
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 18
+          },
+          "name": "readonlyProperty",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 20
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
+    "jsii-calc.ExperimentalEnum": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "jsii-calc.ExperimentalEnum",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 31
+      },
+      "members": [
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "name": "OptionA"
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "name": "OptionB"
+        }
+      ],
+      "name": "ExperimentalEnum"
+    },
+    "jsii-calc.ExperimentalStruct": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "jsii-calc.ExperimentalStruct",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 4
+      },
+      "name": "ExperimentalStruct",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 6
+          },
+          "name": "readonlyProperty",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
+    },
     "jsii-calc.ExportedBaseClass": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.ExportedBaseClass",
@@ -2729,6 +2926,95 @@
         }
       ]
     },
+    "jsii-calc.IDeprecatedInterface": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "deprecated": "for the show",
+        "stability": "deprecated"
+      },
+      "fqn": "jsii-calc.IDeprecatedInterface",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 78
+      },
+      "methods": [
+        {
+          "abstract": true,
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 82
+          },
+          "name": "method"
+        }
+      ],
+      "name": "IDeprecatedInterface",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 80
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
+    "jsii-calc.IExperimentalInterface": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "jsii-calc.IExperimentalInterface",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 9
+      },
+      "methods": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 13
+          },
+          "name": "method"
+        }
+      ],
+      "name": "IExperimentalInterface",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 11
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
     "jsii-calc.IExtendsPrivateInterface": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.IExtendsPrivateInterface",
@@ -3358,6 +3644,49 @@
         }
       ]
     },
+    "jsii-calc.IStableInterface": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.IStableInterface",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 44
+      },
+      "methods": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 48
+          },
+          "name": "method"
+        }
+      ],
+      "name": "IStableInterface",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 46
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
     "jsii-calc.ImplementInternalInterface": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.ImplementInternalInterface",
@@ -5745,40 +6074,138 @@
       ],
       "name": "SingleInstanceTwoTypes"
     },
-    "jsii-calc.StabilityTest": {
+    "jsii-calc.StableClass": {
       "assembly": "jsii-calc",
       "docs": {
-        "stability": "stable",
-        "summary": "This enum is there to test various stability levels are correctly emitted."
+        "stability": "stable"
       },
-      "fqn": "jsii-calc.StabilityTest",
-      "kind": "enum",
+      "fqn": "jsii-calc.StableClass",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        },
+        "parameters": [
+          {
+            "name": "readonlyString",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "mutableNumber",
+            "optional": true,
+            "type": {
+              "primitive": "number"
+            }
+          }
+        ]
+      },
+      "kind": "class",
       "locationInModule": {
-        "filename": "lib/compliance.ts",
-        "line": 1721
+        "filename": "lib/stability.ts",
+        "line": 51
       },
-      "members": [
+      "methods": [
         {
           "docs": {
-            "deprecated": "yeah this one's no good",
-            "stability": "deprecated"
+            "stability": "stable"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 62
+          },
+          "name": "method"
+        }
+      ],
+      "name": "StableClass",
+      "properties": [
+        {
+          "docs": {
+            "stability": "stable"
           },
-          "name": "DeprecatedMember"
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 53
+          },
+          "name": "readonlyProperty",
+          "type": {
+            "primitive": "string"
+          }
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "stable"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 55
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
+    "jsii-calc.StableEnum": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.StableEnum",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 65
+      },
+      "members": [
+        {
+          "docs": {
+            "stability": "stable"
           },
-          "name": "ExperimentalMember"
+          "name": "OptionA"
         },
         {
           "docs": {
             "stability": "stable"
           },
-          "name": "StableMember"
+          "name": "OptionB"
         }
       ],
-      "name": "StabilityTest"
+      "name": "StableEnum"
+    },
+    "jsii-calc.StableStruct": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.StableStruct",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 39
+      },
+      "name": "StableStruct",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 41
+          },
+          "name": "readonlyProperty",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
     },
     "jsii-calc.StaticContext": {
       "assembly": "jsii-calc",
@@ -6927,5 +7354,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "UHwu7qd5MqRQCz8lxX6GriJru8ZUKZRu1Oi7QZ3zDnM="
+  "fingerprint": "7WPX4JJX9K3lSIehbMBcjNATyKWXOa3SXA/ct2gisGc="
 }
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Class/ClassGenerator.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Class/ClassGenerator.cs
index c0b644177f..0304f2a9cb 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Class/ClassGenerator.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Class/ClassGenerator.cs
@@ -1,5 +1,6 @@
 using System.Collections.Generic;
 using System.Linq;
+using Amazon.JSII.Generator.DocComment;
 using Amazon.JSII.JsonModel.Spec;
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp;
@@ -123,6 +124,7 @@ IEnumerable<MemberDeclarationSyntax> CreateConstructors()
 
             if (Type.Initializer != null)
             {
+                var docComment = new MethodDocCommentGenerator(Type.Initializer, Symbols).CreateDocComment();
                 yield return SF.ConstructorDeclaration
                 (
                     attributes,
@@ -154,7 +156,7 @@ IEnumerable<MemberDeclarationSyntax> CreateConstructors()
                     ),
                     SF.Block(),
                     null
-                );
+                ).WithLeadingTrivia(docComment);
             }
 
             yield return SF.ConstructorDeclaration
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/DocComment/DocCommentGeneratorBase.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/DocComment/DocCommentGeneratorBase.cs
index 532b24a4dd..398a768fc2 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/DocComment/DocCommentGeneratorBase.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/DocComment/DocCommentGeneratorBase.cs
@@ -53,7 +53,6 @@ protected IEnumerable<XmlNodeSyntax> GetRemarksNodes()
             List<string> remarks = new List<string>();
             if (!String.IsNullOrEmpty(Documentable.Docs.Remarks)) { remarks.Add(Documentable.Docs.Remarks); }
             if (!String.IsNullOrEmpty(Documentable.Docs.Default)) { remarks.Add($"default: {Documentable.Docs.Default}"); }
-            if (!String.IsNullOrEmpty(Documentable.Docs.Deprecated)) { remarks.Add($"deprecated: {Documentable.Docs.Deprecated}"); }
             if (Documentable.Docs.Stability.HasValue) { remarks.Add($"stability: {Documentable.Docs.Stability}"); }
             if (!String.IsNullOrEmpty(Documentable.Docs.Example)) { remarks.Add($"example:\n<code>\n{Documentable.Docs.Example}\n</code>"); }
             if (!String.IsNullOrEmpty(Documentable.Docs.See)) { remarks.Add($"{Documentable.Docs.See} "); } // Extra space here to keep links clickable
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/DocComment/MethodDocCommentGenerator.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/DocComment/MethodDocCommentGenerator.cs
index 78b645a68c..62b728aa3a 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/DocComment/MethodDocCommentGenerator.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/DocComment/MethodDocCommentGenerator.cs
@@ -8,11 +8,11 @@
 
 namespace Amazon.JSII.Generator.DocComment
 {
-    public class MethodDocCommentGenerator : DocCommentGeneratorBase<Method>
+    public class MethodDocCommentGenerator : DocCommentGeneratorBase<Callable>
     {
         readonly ISymbolMap _symbols;
 
-        public MethodDocCommentGenerator(Method documentable, ISymbolMap symbols) : base(documentable)
+        public MethodDocCommentGenerator(Callable documentable, ISymbolMap symbols) : base(documentable)
         {
             _symbols = symbols ?? throw new ArgumentNullException(nameof(symbols));
         }
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Enum/EnumGenerator.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Enum/EnumGenerator.cs
index 0105794202..bbde6173a7 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Enum/EnumGenerator.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/Enum/EnumGenerator.cs
@@ -68,14 +68,7 @@ EnumMemberDeclarationSyntax GetMemberDeclaration(EnumMember member)
             {
                 EnumMemberDeclarationSyntax declaration = SF.EnumMemberDeclaration
                 (
-                    SF.List(new[] {
-                        SF.AttributeList(SF.SeparatedList(new[] {
-                            SF.Attribute(
-                                SF.ParseName("JsiiEnumMember"),
-                                SF.ParseAttributeArgumentList($"(name: \"{member.Name}\")")
-                            )
-                        }))
-                    }),
+                    SF.List(GetAttributeLists()),
                     Symbols.GetNameSyntaxToken(Type, member),
                     null
                 );
@@ -89,6 +82,26 @@ EnumMemberDeclarationSyntax GetMemberDeclaration(EnumMember member)
                 }
 
                 return declaration;
+
+                IEnumerable<AttributeListSyntax> GetAttributeLists()
+                {
+                    yield return SF.AttributeList(SF.SingletonSeparatedList(
+                        SF.Attribute(
+                            SF.ParseName("JsiiEnumMember"),
+                            SF.ParseAttributeArgumentList($"(name: \"{member.Name}\")")
+                        )
+                    ));
+
+                    if (member.Docs?.Stability == Stability.Deprecated)
+                    {
+                        yield return SF.AttributeList(SF.SingletonSeparatedList(
+                            SF.Attribute(
+                                SF.ParseName("System.Obsolete"),
+                                SF.ParseAttributeArgumentList($"({SF.Literal(member.Docs?.Deprecated ?? "")})")
+                            )
+                        ));
+                    }
+                }
             }
         }
     }
diff --git a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/TypeProxyGeneratorBase.cs b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/TypeProxyGeneratorBase.cs
index e184e1a369..5733dba5a7 100644
--- a/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/TypeProxyGeneratorBase.cs
+++ b/packages/jsii-dotnet-generator/src/Amazon.JSII.Generator/TypeProxyGeneratorBase.cs
@@ -35,16 +35,27 @@ SyntaxList<AttributeListSyntax> CreateAttributes()
                 var typeOfExpression = SF.TypeOfExpression(Symbols.GetNameSyntax(Type));
                 var fullyQualifiedNameLiteral = SF.Literal(Type.FullyQualifiedName);
 
-                return SF.List(new[]
+                return SF.List(GetAttributeLists());
+
+                IEnumerable<AttributeListSyntax> GetAttributeLists()
                 {
-                    SF.AttributeList(SF.SeparatedList(new[]
-                    {
+                    yield return SF.AttributeList(SF.SingletonSeparatedList(
                         SF.Attribute(
                             SF.ParseName("JsiiTypeProxy"),
                             SF.ParseAttributeArgumentList($"(nativeType: {typeOfExpression}, fullyQualifiedName: {fullyQualifiedNameLiteral})")
                         )
-                    }))
-                });
+                    ));
+
+                    if (Type.Docs?.Stability == Stability.Deprecated)
+                    {
+                        yield return SF.AttributeList(SF.SingletonSeparatedList(
+                            SF.Attribute(
+                                SF.ParseName("System.Obsolete"),
+                                SF.ParseAttributeArgumentList($"({SF.Literal(Type.Docs?.Deprecated ?? "")})")
+                            )
+                        ));
+                    }
+                }
             }
 
             BaseListSyntax CreateBaseList()
diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
index c3a6ee2f6d..47db0ed5b1 100644
--- a/packages/jsii-pacmak/lib/targets/java.ts
+++ b/packages/jsii-pacmak/lib/targets/java.ts
@@ -311,6 +311,7 @@ class JavaGenerator extends Generator {
         const nested = this.isNested(ifc);
         const inner = nested ? ' static' : '';
         if (!nested) { this.emitGeneratedAnnotation(); }
+        this.emitStabilityAnnotations(ifc);
         this.code.openBlock(`public${inner} interface ${ifc.name} extends ${bases}`);
     }
 
@@ -329,6 +330,7 @@ class JavaGenerator extends Generator {
     protected onInterfaceMethod(_ifc: spec.InterfaceType, method: spec.Method) {
         const returnType = method.returns ? this.toJavaType(method.returns.type) : 'void';
         this.addJavaDocs(method);
+        this.emitStabilityAnnotations(method);
         this.code.line(`${returnType} ${method.name}(${this.renderMethodParameters(method)});`);
     }
 
@@ -343,6 +345,7 @@ class JavaGenerator extends Generator {
 
         // for unions we only generate overloads for setters, not getters.
         this.addJavaDocs(prop);
+        this.emitStabilityAnnotations(prop);
         this.code.line(`${getterType} get${propName}();`);
 
         if (!prop.immutable) {
@@ -764,6 +767,7 @@ class JavaGenerator extends Generator {
         this.code.line('/**');
         this.code.line(` * @return a {@link Builder} of {@link ${interfaceName}}`);
         this.code.line(' */');
+        this.emitStabilityAnnotations(ifc);
         this.code.openBlock(`static ${builderName} builder()`);
         this.code.line(`return new ${builderName}();`);
         this.code.closeBlock();
@@ -816,6 +820,7 @@ class JavaGenerator extends Generator {
         this.code.line('/**');
         this.code.line(` * A builder for {@link ${interfaceName}}`);
         this.code.line(' */');
+        this.emitStabilityAnnotations(ifc);
         this.code.openBlock(`final class ${builderName}`);
 
         for (const prop of props) {
@@ -835,7 +840,11 @@ class JavaGenerator extends Generator {
                     this.code.line(` * @param value the value to be set`);
                 }
                 this.code.line(` * @return {@code this}`);
+                if (prop.docs && prop.docs.deprecated) {
+                    this.code.line(` * @deprecated ${prop.docs.deprecated}`);
+                }
                 this.code.line(' */');
+                this.emitStabilityAnnotations(prop.spec);
                 this.code.openBlock(`public ${builderName} with${prop.propName}(${prop.nullable ? `${JSR305_NULLABLE} ` : ''}final ${type} value)`);
                 this.code.line(`this._${prop.fieldName} = ${_validateIfNonOptional('value', prop)};`);
                 this.code.line('return this;');
@@ -848,6 +857,7 @@ class JavaGenerator extends Generator {
         this.code.line(` * @return a new instance of {@link ${interfaceName}}`);
         this.code.line(' * @throws NullPointerException if any required attribute was not provided');
         this.code.line(' */');
+        this.emitStabilityAnnotations(ifc);
         this.code.openBlock(`public ${interfaceName} build()`);
         this.code.openBlock(`return new ${interfaceName}()`);
         for (const prop of props) {
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/Amazon/JSII/Tests/CalculatorNamespace/LibNamespace/Number.cs b/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/Amazon/JSII/Tests/CalculatorNamespace/LibNamespace/Number.cs
index bc1268d445..017f1346d2 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/Amazon/JSII/Tests/CalculatorNamespace/LibNamespace/Number.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/Amazon/JSII/Tests/CalculatorNamespace/LibNamespace/Number.cs
@@ -6,6 +6,8 @@ namespace Amazon.JSII.Tests.CalculatorNamespace.LibNamespace
     [JsiiClass(nativeType: typeof(Number), fullyQualifiedName: "@scope/jsii-calc-lib.Number", parametersJson: "[{\"name\":\"value\",\"type\":{\"primitive\":\"number\"}}]")]
     public class Number : Value_, IIDoublable
     {
+        /// <summary>Creates a Number object.</summary>
+        /// <param name = "value">The number.</param>
         public Number(double value): base(new DeputyProps(new object[]{value}))
         {
         }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
index 4403c079d7..a6b8a4027a 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
@@ -1892,76 +1892,140 @@
     "jsii-calc.DeprecatedClass": {
       "assembly": "jsii-calc",
       "docs": {
-        "deprecated": "without replacement",
-        "stability": "deprecated",
-        "summary": "This tests code generation of deprecation markers."
+        "deprecated": "for the show",
+        "stability": "deprecated"
       },
       "fqn": "jsii-calc.DeprecatedClass",
       "initializer": {
         "docs": {
-          "deprecated": "this is unsafe",
+          "deprecated": "for the show",
           "stability": "deprecated"
         },
         "parameters": [
           {
-            "docs": {
-              "summary": "some string."
-            },
-            "name": "argument",
-            "optional": true,
+            "name": "readonlyString",
             "type": {
               "primitive": "string"
             }
+          },
+          {
+            "name": "mutableNumber",
+            "optional": true,
+            "type": {
+              "primitive": "number"
+            }
           }
         ]
       },
       "kind": "class",
       "locationInModule": {
-        "filename": "lib/compliance.ts",
-        "line": 1690
+        "filename": "lib/stability.ts",
+        "line": 85
       },
       "methods": [
         {
           "docs": {
-            "deprecated": "throws unexpected errors",
+            "deprecated": "for the show",
             "stability": "deprecated"
           },
           "locationInModule": {
-            "filename": "lib/compliance.ts",
-            "line": 1712
+            "filename": "lib/stability.ts",
+            "line": 96
           },
-          "name": "deprecatedMethod"
+          "name": "method"
         }
       ],
       "name": "DeprecatedClass",
       "properties": [
         {
           "docs": {
-            "deprecated": "intentionally",
+            "deprecated": "for the show",
             "stability": "deprecated"
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "lib/compliance.ts",
-            "line": 1694
+            "filename": "lib/stability.ts",
+            "line": 87
           },
-          "name": "deprecatedAttribute",
+          "name": "readonlyProperty",
           "type": {
             "primitive": "string"
           }
         },
         {
           "docs": {
-            "deprecated": "can be unexpectedly non-null!",
+            "deprecated": "for the show",
             "stability": "deprecated"
           },
           "locationInModule": {
-            "filename": "lib/compliance.ts",
-            "line": 1699
+            "filename": "lib/stability.ts",
+            "line": 89
           },
-          "name": "deprecatedProtected",
+          "name": "mutableProperty",
           "optional": true,
-          "protected": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
+    "jsii-calc.DeprecatedEnum": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "deprecated": "for the show",
+        "stability": "deprecated"
+      },
+      "fqn": "jsii-calc.DeprecatedEnum",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 99
+      },
+      "members": [
+        {
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "name": "OptionA"
+        },
+        {
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "name": "OptionB"
+        }
+      ],
+      "name": "DeprecatedEnum"
+    },
+    "jsii-calc.DeprecatedStruct": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "deprecated": "for the show",
+        "stability": "deprecated"
+      },
+      "fqn": "jsii-calc.DeprecatedStruct",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 73
+      },
+      "name": "DeprecatedStruct",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 75
+          },
+          "name": "readonlyProperty",
           "type": {
             "primitive": "string"
           }
@@ -2475,6 +2539,139 @@
         }
       ]
     },
+    "jsii-calc.ExperimentalClass": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "jsii-calc.ExperimentalClass",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        },
+        "parameters": [
+          {
+            "name": "readonlyString",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "mutableNumber",
+            "optional": true,
+            "type": {
+              "primitive": "number"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 16
+      },
+      "methods": [
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 28
+          },
+          "name": "method"
+        }
+      ],
+      "name": "ExperimentalClass",
+      "properties": [
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 18
+          },
+          "name": "readonlyProperty",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 20
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
+    "jsii-calc.ExperimentalEnum": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "jsii-calc.ExperimentalEnum",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 31
+      },
+      "members": [
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "name": "OptionA"
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "name": "OptionB"
+        }
+      ],
+      "name": "ExperimentalEnum"
+    },
+    "jsii-calc.ExperimentalStruct": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "jsii-calc.ExperimentalStruct",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 4
+      },
+      "name": "ExperimentalStruct",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 6
+          },
+          "name": "readonlyProperty",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
+    },
     "jsii-calc.ExportedBaseClass": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.ExportedBaseClass",
@@ -2729,6 +2926,95 @@
         }
       ]
     },
+    "jsii-calc.IDeprecatedInterface": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "deprecated": "for the show",
+        "stability": "deprecated"
+      },
+      "fqn": "jsii-calc.IDeprecatedInterface",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 78
+      },
+      "methods": [
+        {
+          "abstract": true,
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 82
+          },
+          "name": "method"
+        }
+      ],
+      "name": "IDeprecatedInterface",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "deprecated": "for the show",
+            "stability": "deprecated"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 80
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
+    "jsii-calc.IExperimentalInterface": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "jsii-calc.IExperimentalInterface",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 9
+      },
+      "methods": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 13
+          },
+          "name": "method"
+        }
+      ],
+      "name": "IExperimentalInterface",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 11
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
     "jsii-calc.IExtendsPrivateInterface": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.IExtendsPrivateInterface",
@@ -3358,6 +3644,49 @@
         }
       ]
     },
+    "jsii-calc.IStableInterface": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.IStableInterface",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 44
+      },
+      "methods": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 48
+          },
+          "name": "method"
+        }
+      ],
+      "name": "IStableInterface",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 46
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
     "jsii-calc.ImplementInternalInterface": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.ImplementInternalInterface",
@@ -5745,40 +6074,138 @@
       ],
       "name": "SingleInstanceTwoTypes"
     },
-    "jsii-calc.StabilityTest": {
+    "jsii-calc.StableClass": {
       "assembly": "jsii-calc",
       "docs": {
-        "stability": "stable",
-        "summary": "This enum is there to test various stability levels are correctly emitted."
+        "stability": "stable"
       },
-      "fqn": "jsii-calc.StabilityTest",
-      "kind": "enum",
+      "fqn": "jsii-calc.StableClass",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        },
+        "parameters": [
+          {
+            "name": "readonlyString",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "mutableNumber",
+            "optional": true,
+            "type": {
+              "primitive": "number"
+            }
+          }
+        ]
+      },
+      "kind": "class",
       "locationInModule": {
-        "filename": "lib/compliance.ts",
-        "line": 1721
+        "filename": "lib/stability.ts",
+        "line": 51
       },
-      "members": [
+      "methods": [
         {
           "docs": {
-            "deprecated": "yeah this one's no good",
-            "stability": "deprecated"
+            "stability": "stable"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 62
+          },
+          "name": "method"
+        }
+      ],
+      "name": "StableClass",
+      "properties": [
+        {
+          "docs": {
+            "stability": "stable"
           },
-          "name": "DeprecatedMember"
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 53
+          },
+          "name": "readonlyProperty",
+          "type": {
+            "primitive": "string"
+          }
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "stable"
+          },
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 55
+          },
+          "name": "mutableProperty",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ]
+    },
+    "jsii-calc.StableEnum": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.StableEnum",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 65
+      },
+      "members": [
+        {
+          "docs": {
+            "stability": "stable"
           },
-          "name": "ExperimentalMember"
+          "name": "OptionA"
         },
         {
           "docs": {
             "stability": "stable"
           },
-          "name": "StableMember"
+          "name": "OptionB"
         }
       ],
-      "name": "StabilityTest"
+      "name": "StableEnum"
+    },
+    "jsii-calc.StableStruct": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.StableStruct",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/stability.ts",
+        "line": 39
+      },
+      "name": "StableStruct",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/stability.ts",
+            "line": 41
+          },
+          "name": "readonlyProperty",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
     },
     "jsii-calc.StaticContext": {
       "assembly": "jsii-calc",
@@ -6927,5 +7354,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "UHwu7qd5MqRQCz8lxX6GriJru8ZUKZRu1Oi7QZ3zDnM="
+  "fingerprint": "7WPX4JJX9K3lSIehbMBcjNATyKWXOa3SXA/ct2gisGc="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Add.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Add.cs
index 6384f12c27..52e1600818 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Add.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Add.cs
@@ -7,6 +7,9 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
     [JsiiClass(nativeType: typeof(Add), fullyQualifiedName: "jsii-calc.Add", parametersJson: "[{\"name\":\"lhs\",\"type\":{\"fqn\":\"@scope/jsii-calc-lib.Value\"}},{\"name\":\"rhs\",\"type\":{\"fqn\":\"@scope/jsii-calc-lib.Value\"}}]")]
     public class Add : BinaryOperation
     {
+        /// <summary>Creates a BinaryOperation.</summary>
+        /// <param name = "lhs">Left-hand side operand.</param>
+        /// <param name = "rhs">Right-hand side operand.</param>
         public Add(Value_ lhs, Value_ rhs): base(new DeputyProps(new object[]{lhs, rhs}))
         {
         }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/BinaryOperation.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/BinaryOperation.cs
index 8cba22822f..a683be181e 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/BinaryOperation.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/BinaryOperation.cs
@@ -7,6 +7,9 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
     [JsiiClass(nativeType: typeof(BinaryOperation), fullyQualifiedName: "jsii-calc.BinaryOperation", parametersJson: "[{\"name\":\"lhs\",\"type\":{\"fqn\":\"@scope/jsii-calc-lib.Value\"}},{\"name\":\"rhs\",\"type\":{\"fqn\":\"@scope/jsii-calc-lib.Value\"}}]")]
     public abstract class BinaryOperation : Operation, IIFriendly
     {
+        /// <summary>Creates a BinaryOperation.</summary>
+        /// <param name = "lhs">Left-hand side operand.</param>
+        /// <param name = "rhs">Right-hand side operand.</param>
         protected BinaryOperation(Value_ lhs, Value_ rhs): base(new DeputyProps(new object[]{lhs, rhs}))
         {
         }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Calculator.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Calculator.cs
index 471950846a..4b35fc8783 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Calculator.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Calculator.cs
@@ -9,6 +9,8 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
     [JsiiClass(nativeType: typeof(Calculator), fullyQualifiedName: "jsii-calc.Calculator", parametersJson: "[{\"name\":\"props\",\"type\":{\"fqn\":\"jsii-calc.CalculatorProps\"},\"optional\":true}]")]
     public class Calculator : CompositeOperation_
     {
+        /// <summary>Creates a Calculator object.</summary>
+        /// <param name = "props">Initialization properties.</param>
         public Calculator(ICalculatorProps props): base(new DeputyProps(new object[]{props}))
         {
         }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
index 533f8cc932..77234ee5e2 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
@@ -2,60 +2,48 @@
 
 namespace Amazon.JSII.Tests.CalculatorNamespace
 {
-    /// <summary>This tests code generation of deprecation markers.</summary>
-    /// <remarks>
-    /// deprecated: without replacement
-    /// stability: Deprecated
-    /// </remarks>
-    [JsiiClass(nativeType: typeof(DeprecatedClass), fullyQualifiedName: "jsii-calc.DeprecatedClass", parametersJson: "[{\"name\":\"argument\",\"type\":{\"primitive\":\"string\"},\"optional\":true}]")]
-    [System.Obsolete("without replacement")]
+    /// <remarks>stability: Deprecated</remarks>
+    [JsiiClass(nativeType: typeof(DeprecatedClass), fullyQualifiedName: "jsii-calc.DeprecatedClass", parametersJson: "[{\"name\":\"readonlyString\",\"type\":{\"primitive\":\"string\"}},{\"name\":\"mutableNumber\",\"type\":{\"primitive\":\"number\"},\"optional\":true}]")]
+    [System.Obsolete("for the show")]
     public class DeprecatedClass : DeputyBase
     {
-        [System.Obsolete("this is unsafe")]
-        public DeprecatedClass(string argument): base(new DeputyProps(new object[]{argument}))
+        /// <remarks>stability: Deprecated</remarks>
+        [System.Obsolete("for the show")]
+        public DeprecatedClass(string readonlyString, double? mutableNumber): base(new DeputyProps(new object[]{readonlyString, mutableNumber}))
         {
         }
 
-        [System.Obsolete("this is unsafe")]
+        [System.Obsolete("for the show")]
         protected DeprecatedClass(ByRefValue reference): base(reference)
         {
         }
 
-        [System.Obsolete("this is unsafe")]
+        [System.Obsolete("for the show")]
         protected DeprecatedClass(DeputyProps props): base(props)
         {
         }
 
-        /// <remarks>
-        /// deprecated: intentionally
-        /// stability: Deprecated
-        /// </remarks>
-        [JsiiProperty(name: "deprecatedAttribute", typeJson: "{\"primitive\":\"string\"}")]
-        [System.Obsolete("intentionally")]
-        public virtual string DeprecatedAttribute
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        [System.Obsolete("for the show")]
+        public virtual string ReadonlyProperty
         {
             get => GetInstanceProperty<string>();
         }
 
-        /// <remarks>
-        /// deprecated: can be unexpectedly non-null!
-        /// stability: Deprecated
-        /// </remarks>
-        [JsiiProperty(name: "deprecatedProtected", typeJson: "{\"primitive\":\"string\"}", isOptional: true)]
-        [System.Obsolete("can be unexpectedly non-null!")]
-        protected virtual string DeprecatedProtected
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        [System.Obsolete("for the show")]
+        public virtual double? MutableProperty
         {
-            get => GetInstanceProperty<string>();
+            get => GetInstanceProperty<double? >();
             set => SetInstanceProperty(value);
         }
 
-        /// <remarks>
-        /// deprecated: throws unexpected errors
-        /// stability: Deprecated
-        /// </remarks>
-        [JsiiMethod(name: "deprecatedMethod")]
-        [System.Obsolete("throws unexpected errors")]
-        public virtual void DeprecatedMethod()
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiMethod(name: "method")]
+        [System.Obsolete("for the show")]
+        public virtual void Method()
         {
             InvokeInstanceVoidMethod(new object[]{});
         }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedEnum.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedEnum.cs
new file mode 100644
index 0000000000..48cf148fa5
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedEnum.cs
@@ -0,0 +1,19 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Deprecated</remarks>
+    [JsiiEnum(nativeType: typeof(DeprecatedEnum), fullyQualifiedName: "jsii-calc.DeprecatedEnum")]
+    [System.Obsolete("for the show")]
+    public enum DeprecatedEnum
+    {
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiEnumMember(name: "OptionA")]
+        [System.Obsolete("for the show")]
+        OptionA,
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiEnumMember(name: "OptionB")]
+        [System.Obsolete("for the show")]
+        OptionB
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStruct.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStruct.cs
new file mode 100644
index 0000000000..5f8f8545af
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStruct.cs
@@ -0,0 +1,18 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Deprecated</remarks>
+    [JsiiByValue]
+    public class DeprecatedStruct : IDeprecatedStruct
+    {
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}", isOverride: true)]
+        [System.Obsolete("for the show")]
+        public string ReadonlyProperty
+        {
+            get;
+            set;
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStructProxy.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStructProxy.cs
new file mode 100644
index 0000000000..aabfe4dbc1
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStructProxy.cs
@@ -0,0 +1,22 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Deprecated</remarks>
+    [JsiiTypeProxy(nativeType: typeof(IDeprecatedStruct), fullyQualifiedName: "jsii-calc.DeprecatedStruct")]
+    [System.Obsolete("for the show")]
+    internal sealed class DeprecatedStructProxy : DeputyBase, IDeprecatedStruct
+    {
+        private DeprecatedStructProxy(ByRefValue reference): base(reference)
+        {
+        }
+
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        [System.Obsolete("for the show")]
+        public string ReadonlyProperty
+        {
+            get => GetInstanceProperty<string>();
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalClass.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalClass.cs
new file mode 100644
index 0000000000..a652fd8761
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalClass.cs
@@ -0,0 +1,44 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Experimental</remarks>
+    [JsiiClass(nativeType: typeof(ExperimentalClass), fullyQualifiedName: "jsii-calc.ExperimentalClass", parametersJson: "[{\"name\":\"readonlyString\",\"type\":{\"primitive\":\"string\"}},{\"name\":\"mutableNumber\",\"type\":{\"primitive\":\"number\"},\"optional\":true}]")]
+    public class ExperimentalClass : DeputyBase
+    {
+        /// <remarks>stability: Experimental</remarks>
+        public ExperimentalClass(string readonlyString, double? mutableNumber): base(new DeputyProps(new object[]{readonlyString, mutableNumber}))
+        {
+        }
+
+        protected ExperimentalClass(ByRefValue reference): base(reference)
+        {
+        }
+
+        protected ExperimentalClass(DeputyProps props): base(props)
+        {
+        }
+
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        public virtual string ReadonlyProperty
+        {
+            get => GetInstanceProperty<string>();
+        }
+
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        public virtual double? MutableProperty
+        {
+            get => GetInstanceProperty<double? >();
+            set => SetInstanceProperty(value);
+        }
+
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiMethod(name: "method")]
+        public virtual void Method()
+        {
+            InvokeInstanceVoidMethod(new object[]{});
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalEnum.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalEnum.cs
new file mode 100644
index 0000000000..7337ef57c4
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalEnum.cs
@@ -0,0 +1,16 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Experimental</remarks>
+    [JsiiEnum(nativeType: typeof(ExperimentalEnum), fullyQualifiedName: "jsii-calc.ExperimentalEnum")]
+    public enum ExperimentalEnum
+    {
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiEnumMember(name: "OptionA")]
+        OptionA,
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiEnumMember(name: "OptionB")]
+        OptionB
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalStruct.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalStruct.cs
new file mode 100644
index 0000000000..5ba3647e64
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalStruct.cs
@@ -0,0 +1,17 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Experimental</remarks>
+    [JsiiByValue]
+    public class ExperimentalStruct : IExperimentalStruct
+    {
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}", isOverride: true)]
+        public string ReadonlyProperty
+        {
+            get;
+            set;
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalStructProxy.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalStructProxy.cs
new file mode 100644
index 0000000000..f38d82ecf3
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/ExperimentalStructProxy.cs
@@ -0,0 +1,20 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Experimental</remarks>
+    [JsiiTypeProxy(nativeType: typeof(IExperimentalStruct), fullyQualifiedName: "jsii-calc.ExperimentalStruct")]
+    internal sealed class ExperimentalStructProxy : DeputyBase, IExperimentalStruct
+    {
+        private ExperimentalStructProxy(ByRefValue reference): base(reference)
+        {
+        }
+
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        public string ReadonlyProperty
+        {
+            get => GetInstanceProperty<string>();
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedInterfaceProxy.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedInterfaceProxy.cs
new file mode 100644
index 0000000000..710e3cf733
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedInterfaceProxy.cs
@@ -0,0 +1,31 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Deprecated</remarks>
+    [JsiiTypeProxy(nativeType: typeof(IIDeprecatedInterface), fullyQualifiedName: "jsii-calc.IDeprecatedInterface")]
+    [System.Obsolete("for the show")]
+    internal sealed class IDeprecatedInterfaceProxy : DeputyBase, IIDeprecatedInterface
+    {
+        private IDeprecatedInterfaceProxy(ByRefValue reference): base(reference)
+        {
+        }
+
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        [System.Obsolete("for the show")]
+        public double? MutableProperty
+        {
+            get => GetInstanceProperty<double? >();
+            set => SetInstanceProperty(value);
+        }
+
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiMethod(name: "method")]
+        [System.Obsolete("for the show")]
+        public void Method()
+        {
+            InvokeInstanceVoidMethod(new object[]{});
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedStruct.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedStruct.cs
new file mode 100644
index 0000000000..c822069170
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedStruct.cs
@@ -0,0 +1,18 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Deprecated</remarks>
+    [JsiiInterface(nativeType: typeof(IDeprecatedStruct), fullyQualifiedName: "jsii-calc.DeprecatedStruct")]
+    [System.Obsolete("for the show")]
+    public interface IDeprecatedStruct
+    {
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        [System.Obsolete("for the show")]
+        string ReadonlyProperty
+        {
+            get;
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IExperimentalInterfaceProxy.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IExperimentalInterfaceProxy.cs
new file mode 100644
index 0000000000..591b8a49f7
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IExperimentalInterfaceProxy.cs
@@ -0,0 +1,28 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Experimental</remarks>
+    [JsiiTypeProxy(nativeType: typeof(IIExperimentalInterface), fullyQualifiedName: "jsii-calc.IExperimentalInterface")]
+    internal sealed class IExperimentalInterfaceProxy : DeputyBase, IIExperimentalInterface
+    {
+        private IExperimentalInterfaceProxy(ByRefValue reference): base(reference)
+        {
+        }
+
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        public double? MutableProperty
+        {
+            get => GetInstanceProperty<double? >();
+            set => SetInstanceProperty(value);
+        }
+
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiMethod(name: "method")]
+        public void Method()
+        {
+            InvokeInstanceVoidMethod(new object[]{});
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IExperimentalStruct.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IExperimentalStruct.cs
new file mode 100644
index 0000000000..13dc6db4c9
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IExperimentalStruct.cs
@@ -0,0 +1,16 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Experimental</remarks>
+    [JsiiInterface(nativeType: typeof(IExperimentalStruct), fullyQualifiedName: "jsii-calc.ExperimentalStruct")]
+    public interface IExperimentalStruct
+    {
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        string ReadonlyProperty
+        {
+            get;
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIDeprecatedInterface.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIDeprecatedInterface.cs
new file mode 100644
index 0000000000..2ee06030b7
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIDeprecatedInterface.cs
@@ -0,0 +1,24 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Deprecated</remarks>
+    [JsiiInterface(nativeType: typeof(IIDeprecatedInterface), fullyQualifiedName: "jsii-calc.IDeprecatedInterface")]
+    [System.Obsolete("for the show")]
+    public interface IIDeprecatedInterface
+    {
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        [System.Obsolete("for the show")]
+        double? MutableProperty
+        {
+            get;
+            set;
+        }
+
+        /// <remarks>stability: Deprecated</remarks>
+        [JsiiMethod(name: "method")]
+        [System.Obsolete("for the show")]
+        void Method();
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIExperimentalInterface.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIExperimentalInterface.cs
new file mode 100644
index 0000000000..9c413e4d2c
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIExperimentalInterface.cs
@@ -0,0 +1,21 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Experimental</remarks>
+    [JsiiInterface(nativeType: typeof(IIExperimentalInterface), fullyQualifiedName: "jsii-calc.IExperimentalInterface")]
+    public interface IIExperimentalInterface
+    {
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        double? MutableProperty
+        {
+            get;
+            set;
+        }
+
+        /// <remarks>stability: Experimental</remarks>
+        [JsiiMethod(name: "method")]
+        void Method();
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIStableInterface.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIStableInterface.cs
new file mode 100644
index 0000000000..8667119549
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIStableInterface.cs
@@ -0,0 +1,21 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Stable</remarks>
+    [JsiiInterface(nativeType: typeof(IIStableInterface), fullyQualifiedName: "jsii-calc.IStableInterface")]
+    public interface IIStableInterface
+    {
+        /// <remarks>stability: Stable</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        double? MutableProperty
+        {
+            get;
+            set;
+        }
+
+        /// <remarks>stability: Stable</remarks>
+        [JsiiMethod(name: "method")]
+        void Method();
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IStableInterfaceProxy.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IStableInterfaceProxy.cs
new file mode 100644
index 0000000000..28be3607cd
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IStableInterfaceProxy.cs
@@ -0,0 +1,28 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Stable</remarks>
+    [JsiiTypeProxy(nativeType: typeof(IIStableInterface), fullyQualifiedName: "jsii-calc.IStableInterface")]
+    internal sealed class IStableInterfaceProxy : DeputyBase, IIStableInterface
+    {
+        private IStableInterfaceProxy(ByRefValue reference): base(reference)
+        {
+        }
+
+        /// <remarks>stability: Stable</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        public double? MutableProperty
+        {
+            get => GetInstanceProperty<double? >();
+            set => SetInstanceProperty(value);
+        }
+
+        /// <remarks>stability: Stable</remarks>
+        [JsiiMethod(name: "method")]
+        public void Method()
+        {
+            InvokeInstanceVoidMethod(new object[]{});
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IStableStruct.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IStableStruct.cs
new file mode 100644
index 0000000000..d97b6c563c
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IStableStruct.cs
@@ -0,0 +1,16 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Stable</remarks>
+    [JsiiInterface(nativeType: typeof(IStableStruct), fullyQualifiedName: "jsii-calc.StableStruct")]
+    public interface IStableStruct
+    {
+        /// <remarks>stability: Stable</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        string ReadonlyProperty
+        {
+            get;
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Multiply.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Multiply.cs
index 1d8db3676c..85ff70bf99 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Multiply.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Multiply.cs
@@ -7,6 +7,9 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
     [JsiiClass(nativeType: typeof(Multiply), fullyQualifiedName: "jsii-calc.Multiply", parametersJson: "[{\"name\":\"lhs\",\"type\":{\"fqn\":\"@scope/jsii-calc-lib.Value\"}},{\"name\":\"rhs\",\"type\":{\"fqn\":\"@scope/jsii-calc-lib.Value\"}}]")]
     public class Multiply : BinaryOperation, IIFriendlier, IIRandomNumberGenerator
     {
+        /// <summary>Creates a BinaryOperation.</summary>
+        /// <param name = "lhs">Left-hand side operand.</param>
+        /// <param name = "rhs">Right-hand side operand.</param>
         public Multiply(Value_ lhs, Value_ rhs): base(new DeputyProps(new object[]{lhs, rhs}))
         {
         }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Old.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Old.cs
index 18a49b7c9a..4c51606c61 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Old.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Old.cs
@@ -3,10 +3,7 @@
 namespace Amazon.JSII.Tests.CalculatorNamespace
 {
     /// <summary>Old class.</summary>
-    /// <remarks>
-    /// deprecated: Use the new class
-    /// stability: Deprecated
-    /// </remarks>
+    /// <remarks>stability: Deprecated</remarks>
     [JsiiClass(nativeType: typeof(Old), fullyQualifiedName: "jsii-calc.Old")]
     [System.Obsolete("Use the new class")]
     public class Old : DeputyBase
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Power.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Power.cs
index 70182dc48b..40f833dc1e 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Power.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/Power.cs
@@ -8,6 +8,9 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
     [JsiiClass(nativeType: typeof(Power), fullyQualifiedName: "jsii-calc.Power", parametersJson: "[{\"name\":\"base\",\"type\":{\"fqn\":\"@scope/jsii-calc-lib.Value\"}},{\"name\":\"pow\",\"type\":{\"fqn\":\"@scope/jsii-calc-lib.Value\"}}]")]
     public class Power : CompositeOperation_
     {
+        /// <summary>Creates a Power operation.</summary>
+        /// <param name = "@base">The base of the power.</param>
+        /// <param name = "pow">The number of times to multiply.</param>
         public Power(Value_ @base, Value_ pow): base(new DeputyProps(new object[]{@base, pow}))
         {
         }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StabilityTest.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StabilityTest.cs
deleted file mode 100644
index fb94f2d85d..0000000000
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StabilityTest.cs
+++ /dev/null
@@ -1,23 +0,0 @@
-using Amazon.JSII.Runtime.Deputy;
-
-namespace Amazon.JSII.Tests.CalculatorNamespace
-{
-    /// <summary>This enum is there to test various stability levels are correctly emitted.</summary>
-    /// <remarks>stability: Stable</remarks>
-    [JsiiEnum(nativeType: typeof(StabilityTest), fullyQualifiedName: "jsii-calc.StabilityTest")]
-    public enum StabilityTest
-    {
-        /// <remarks>
-        /// deprecated: yeah this one's no good
-        /// stability: Deprecated
-        /// </remarks>
-        [JsiiEnumMember(name: "DeprecatedMember")]
-        DeprecatedMember,
-        /// <remarks>stability: Experimental</remarks>
-        [JsiiEnumMember(name: "ExperimentalMember")]
-        ExperimentalMember,
-        /// <remarks>stability: Stable</remarks>
-        [JsiiEnumMember(name: "StableMember")]
-        StableMember
-    }
-}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableClass.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableClass.cs
new file mode 100644
index 0000000000..21d94ee115
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableClass.cs
@@ -0,0 +1,44 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Stable</remarks>
+    [JsiiClass(nativeType: typeof(StableClass), fullyQualifiedName: "jsii-calc.StableClass", parametersJson: "[{\"name\":\"readonlyString\",\"type\":{\"primitive\":\"string\"}},{\"name\":\"mutableNumber\",\"type\":{\"primitive\":\"number\"},\"optional\":true}]")]
+    public class StableClass : DeputyBase
+    {
+        /// <remarks>stability: Stable</remarks>
+        public StableClass(string readonlyString, double? mutableNumber): base(new DeputyProps(new object[]{readonlyString, mutableNumber}))
+        {
+        }
+
+        protected StableClass(ByRefValue reference): base(reference)
+        {
+        }
+
+        protected StableClass(DeputyProps props): base(props)
+        {
+        }
+
+        /// <remarks>stability: Stable</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        public virtual string ReadonlyProperty
+        {
+            get => GetInstanceProperty<string>();
+        }
+
+        /// <remarks>stability: Stable</remarks>
+        [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
+        public virtual double? MutableProperty
+        {
+            get => GetInstanceProperty<double? >();
+            set => SetInstanceProperty(value);
+        }
+
+        /// <remarks>stability: Stable</remarks>
+        [JsiiMethod(name: "method")]
+        public virtual void Method()
+        {
+            InvokeInstanceVoidMethod(new object[]{});
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableEnum.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableEnum.cs
new file mode 100644
index 0000000000..3e84219846
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableEnum.cs
@@ -0,0 +1,16 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Stable</remarks>
+    [JsiiEnum(nativeType: typeof(StableEnum), fullyQualifiedName: "jsii-calc.StableEnum")]
+    public enum StableEnum
+    {
+        /// <remarks>stability: Stable</remarks>
+        [JsiiEnumMember(name: "OptionA")]
+        OptionA,
+        /// <remarks>stability: Stable</remarks>
+        [JsiiEnumMember(name: "OptionB")]
+        OptionB
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableStruct.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableStruct.cs
new file mode 100644
index 0000000000..0be21631b1
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableStruct.cs
@@ -0,0 +1,17 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Stable</remarks>
+    [JsiiByValue]
+    public class StableStruct : IStableStruct
+    {
+        /// <remarks>stability: Stable</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}", isOverride: true)]
+        public string ReadonlyProperty
+        {
+            get;
+            set;
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableStructProxy.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableStructProxy.cs
new file mode 100644
index 0000000000..b3144aec53
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/StableStructProxy.cs
@@ -0,0 +1,20 @@
+using Amazon.JSII.Runtime.Deputy;
+
+namespace Amazon.JSII.Tests.CalculatorNamespace
+{
+    /// <remarks>stability: Stable</remarks>
+    [JsiiTypeProxy(nativeType: typeof(IStableStruct), fullyQualifiedName: "jsii-calc.StableStruct")]
+    internal sealed class StableStructProxy : DeputyBase, IStableStruct
+    {
+        private StableStructProxy(ByRefValue reference): base(reference)
+        {
+        }
+
+        /// <remarks>stability: Stable</remarks>
+        [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
+        public string ReadonlyProperty
+        {
+            get => GetInstanceProperty<string>();
+        }
+    }
+}
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/VariadicMethod.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/VariadicMethod.cs
index fa02b7e62b..b261f906f1 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/VariadicMethod.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/VariadicMethod.cs
@@ -5,6 +5,7 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
     [JsiiClass(nativeType: typeof(VariadicMethod), fullyQualifiedName: "jsii-calc.VariadicMethod", parametersJson: "[{\"name\":\"prefix\",\"variadic\":true,\"type\":{\"primitive\":\"number\"}}]")]
     public class VariadicMethod : DeputyBase
     {
+        /// <param name = "prefix">a prefix that will be use for all values returned by `#asArray`.</param>
         public VariadicMethod(double prefix): base(new DeputyProps(new object[]{prefix}))
         {
         }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
index 52a88d859f..460fede183 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/$Module.java
@@ -40,6 +40,8 @@ protected Class<?> resolveClass(final String fqn) throws ClassNotFoundException
             case "jsii-calc.ConsumersOfThisCrazyTypeSystem": return software.amazon.jsii.tests.calculator.ConsumersOfThisCrazyTypeSystem.class;
             case "jsii-calc.DefaultedConstructorArgument": return software.amazon.jsii.tests.calculator.DefaultedConstructorArgument.class;
             case "jsii-calc.DeprecatedClass": return software.amazon.jsii.tests.calculator.DeprecatedClass.class;
+            case "jsii-calc.DeprecatedEnum": return software.amazon.jsii.tests.calculator.DeprecatedEnum.class;
+            case "jsii-calc.DeprecatedStruct": return software.amazon.jsii.tests.calculator.DeprecatedStruct.class;
             case "jsii-calc.DerivedClassHasNoProperties.Base": return software.amazon.jsii.tests.calculator.DerivedClassHasNoProperties.Base.class;
             case "jsii-calc.DerivedClassHasNoProperties.Derived": return software.amazon.jsii.tests.calculator.DerivedClassHasNoProperties.Derived.class;
             case "jsii-calc.DerivedStruct": return software.amazon.jsii.tests.calculator.DerivedStruct.class;
@@ -50,12 +52,17 @@ protected Class<?> resolveClass(final String fqn) throws ClassNotFoundException
             case "jsii-calc.DoubleTrouble": return software.amazon.jsii.tests.calculator.DoubleTrouble.class;
             case "jsii-calc.EraseUndefinedHashValues": return software.amazon.jsii.tests.calculator.EraseUndefinedHashValues.class;
             case "jsii-calc.EraseUndefinedHashValuesOptions": return software.amazon.jsii.tests.calculator.EraseUndefinedHashValuesOptions.class;
+            case "jsii-calc.ExperimentalClass": return software.amazon.jsii.tests.calculator.ExperimentalClass.class;
+            case "jsii-calc.ExperimentalEnum": return software.amazon.jsii.tests.calculator.ExperimentalEnum.class;
+            case "jsii-calc.ExperimentalStruct": return software.amazon.jsii.tests.calculator.ExperimentalStruct.class;
             case "jsii-calc.ExportedBaseClass": return software.amazon.jsii.tests.calculator.ExportedBaseClass.class;
             case "jsii-calc.ExtendsInternalInterface": return software.amazon.jsii.tests.calculator.ExtendsInternalInterface.class;
             case "jsii-calc.GiveMeStructs": return software.amazon.jsii.tests.calculator.GiveMeStructs.class;
             case "jsii-calc.Greetee": return software.amazon.jsii.tests.calculator.Greetee.class;
             case "jsii-calc.GreetingAugmenter": return software.amazon.jsii.tests.calculator.GreetingAugmenter.class;
             case "jsii-calc.IAnotherPublicInterface": return software.amazon.jsii.tests.calculator.IAnotherPublicInterface.class;
+            case "jsii-calc.IDeprecatedInterface": return software.amazon.jsii.tests.calculator.IDeprecatedInterface.class;
+            case "jsii-calc.IExperimentalInterface": return software.amazon.jsii.tests.calculator.IExperimentalInterface.class;
             case "jsii-calc.IExtendsPrivateInterface": return software.amazon.jsii.tests.calculator.IExtendsPrivateInterface.class;
             case "jsii-calc.IFriendlier": return software.amazon.jsii.tests.calculator.IFriendlier.class;
             case "jsii-calc.IFriendlyRandomGenerator": return software.amazon.jsii.tests.calculator.IFriendlyRandomGenerator.class;
@@ -78,6 +85,7 @@ protected Class<?> resolveClass(final String fqn) throws ClassNotFoundException
             case "jsii-calc.IPublicInterface2": return software.amazon.jsii.tests.calculator.IPublicInterface2.class;
             case "jsii-calc.IRandomNumberGenerator": return software.amazon.jsii.tests.calculator.IRandomNumberGenerator.class;
             case "jsii-calc.IReturnsNumber": return software.amazon.jsii.tests.calculator.IReturnsNumber.class;
+            case "jsii-calc.IStableInterface": return software.amazon.jsii.tests.calculator.IStableInterface.class;
             case "jsii-calc.ImplementInternalInterface": return software.amazon.jsii.tests.calculator.ImplementInternalInterface.class;
             case "jsii-calc.ImplementsInterfaceWithInternal": return software.amazon.jsii.tests.calculator.ImplementsInterfaceWithInternal.class;
             case "jsii-calc.ImplementsInterfaceWithInternalSubclass": return software.amazon.jsii.tests.calculator.ImplementsInterfaceWithInternalSubclass.class;
@@ -118,7 +126,9 @@ protected Class<?> resolveClass(final String fqn) throws ClassNotFoundException
             case "jsii-calc.ReturnsPrivateImplementationOfInterface": return software.amazon.jsii.tests.calculator.ReturnsPrivateImplementationOfInterface.class;
             case "jsii-calc.RuntimeTypeChecking": return software.amazon.jsii.tests.calculator.RuntimeTypeChecking.class;
             case "jsii-calc.SingleInstanceTwoTypes": return software.amazon.jsii.tests.calculator.SingleInstanceTwoTypes.class;
-            case "jsii-calc.StabilityTest": return software.amazon.jsii.tests.calculator.StabilityTest.class;
+            case "jsii-calc.StableClass": return software.amazon.jsii.tests.calculator.StableClass.class;
+            case "jsii-calc.StableEnum": return software.amazon.jsii.tests.calculator.StableEnum.class;
+            case "jsii-calc.StableStruct": return software.amazon.jsii.tests.calculator.StableStruct.class;
             case "jsii-calc.StaticContext": return software.amazon.jsii.tests.calculator.StaticContext.class;
             case "jsii-calc.Statics": return software.amazon.jsii.tests.calculator.Statics.class;
             case "jsii-calc.StringEnum": return software.amazon.jsii.tests.calculator.StringEnum.class;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
index 70a05578e5..68eee6b5a7 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
@@ -1,9 +1,7 @@
 package software.amazon.jsii.tests.calculator;
 
 /**
- * This tests code generation of deprecation markers.
- * 
- * @deprecated without replacement
+ * @deprecated for the show
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
 @Deprecated
@@ -14,59 +12,58 @@ protected DeprecatedClass(final software.amazon.jsii.JsiiObject.InitializationMo
         super(mode);
     }
     /**
-     * @deprecated this is unsafe
-     * @param argument some string.
+     * @deprecated for the show
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
-    public DeprecatedClass(@javax.annotation.Nullable final java.lang.String argument) {
+    public DeprecatedClass(final java.lang.String readonlyString, @javax.annotation.Nullable final java.lang.Number mutableNumber) {
         super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
-        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { argument });
+        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(readonlyString, "readonlyString is required"), mutableNumber });
     }
     /**
-     * @deprecated this is unsafe
+     * @deprecated for the show
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
-    public DeprecatedClass() {
+    public DeprecatedClass(final java.lang.String readonlyString) {
         super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
-        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this);
+        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(readonlyString, "readonlyString is required") });
     }
 
     /**
-     * @deprecated throws unexpected errors
+     * @deprecated for the show
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
-    public void deprecatedMethod() {
-        this.jsiiCall("deprecatedMethod", Void.class);
+    public void method() {
+        this.jsiiCall("method", Void.class);
     }
 
     /**
-     * @deprecated intentionally
+     * @deprecated for the show
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
-    public java.lang.String getDeprecatedAttribute() {
-        return this.jsiiGet("deprecatedAttribute", java.lang.String.class);
+    public java.lang.String getReadonlyProperty() {
+        return this.jsiiGet("readonlyProperty", java.lang.String.class);
     }
 
     /**
-     * @deprecated can be unexpectedly non-null!
+     * @deprecated for the show
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @javax.annotation.Nullable
-    protected java.lang.String getDeprecatedProtected() {
-        return this.jsiiGet("deprecatedProtected", java.lang.String.class);
+    public java.lang.Number getMutableProperty() {
+        return this.jsiiGet("mutableProperty", java.lang.Number.class);
     }
 
     /**
-     * @deprecated can be unexpectedly non-null!
+     * @deprecated for the show
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
-    protected void setDeprecatedProtected(@javax.annotation.Nullable final java.lang.String value) {
-        this.jsiiSet("deprecatedProtected", value);
+    public void setMutableProperty(@javax.annotation.Nullable final java.lang.Number value) {
+        this.jsiiSet("mutableProperty", value);
     }
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedEnum.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedEnum.java
new file mode 100644
index 0000000000..6bd86cbbab
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedEnum.java
@@ -0,0 +1,23 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ * @deprecated for the show
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@Deprecated
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+@software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.DeprecatedEnum")
+public enum DeprecatedEnum {
+    /**
+     * @deprecated for the show
+     */
+    @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+    OptionA,
+    /**
+     * @deprecated for the show
+     */
+    @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+    OptionB,
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java
new file mode 100644
index 0000000000..e55dfb90d3
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java
@@ -0,0 +1,92 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ * @deprecated for the show
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@Deprecated
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+public interface DeprecatedStruct extends software.amazon.jsii.JsiiSerializable {
+    /**
+     * @deprecated for the show
+     */
+    @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+    java.lang.String getReadonlyProperty();
+
+    /**
+     * @return a {@link Builder} of {@link DeprecatedStruct}
+     */
+    @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+    static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * A builder for {@link DeprecatedStruct}
+     */
+    @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+    final class Builder {
+        private java.lang.String _readonlyProperty;
+
+        /**
+         * Sets the value of ReadonlyProperty
+         * @param value the value to be set
+         * @return {@code this}
+         * @deprecated for the show
+         */
+        @Deprecated
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+        public Builder withReadonlyProperty(final java.lang.String value) {
+            this._readonlyProperty = java.util.Objects.requireNonNull(value, "readonlyProperty is required");
+            return this;
+        }
+
+        /**
+         * Builds the configured instance.
+         * @return a new instance of {@link DeprecatedStruct}
+         * @throws NullPointerException if any required attribute was not provided
+         */
+        @Deprecated
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+        public DeprecatedStruct build() {
+            return new DeprecatedStruct() {
+                private final java.lang.String $readonlyProperty = java.util.Objects.requireNonNull(_readonlyProperty, "readonlyProperty is required");
+
+                @Override
+                public java.lang.String getReadonlyProperty() {
+                    return this.$readonlyProperty;
+                }
+
+                public com.fasterxml.jackson.databind.JsonNode $jsii$toJson() {
+                    com.fasterxml.jackson.databind.ObjectMapper om = software.amazon.jsii.JsiiObjectMapper.INSTANCE;
+                    com.fasterxml.jackson.databind.node.ObjectNode obj = com.fasterxml.jackson.databind.node.JsonNodeFactory.instance.objectNode();
+                    obj.set("readonlyProperty", om.valueToTree(this.getReadonlyProperty()));
+                    return obj;
+                }
+
+            };
+        }
+    }
+
+    /**
+     * A proxy class which represents a concrete javascript instance of this type.
+     */
+    final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements software.amazon.jsii.tests.calculator.DeprecatedStruct {
+        protected Jsii$Proxy(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+            super(mode);
+        }
+
+        /**
+         * @deprecated for the show
+         */
+        @Override
+        @Deprecated
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+        public java.lang.String getReadonlyProperty() {
+            return this.jsiiGet("readonlyProperty", java.lang.String.class);
+        }
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalClass.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalClass.java
new file mode 100644
index 0000000000..62c5982e37
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalClass.java
@@ -0,0 +1,62 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ * EXPERIMENTAL
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+@software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.ExperimentalClass")
+public class ExperimentalClass extends software.amazon.jsii.JsiiObject {
+    protected ExperimentalClass(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+        super(mode);
+    }
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    public ExperimentalClass(final java.lang.String readonlyString, @javax.annotation.Nullable final java.lang.Number mutableNumber) {
+        super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
+        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(readonlyString, "readonlyString is required"), mutableNumber });
+    }
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    public ExperimentalClass(final java.lang.String readonlyString) {
+        super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
+        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(readonlyString, "readonlyString is required") });
+    }
+
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    public void method() {
+        this.jsiiCall("method", Void.class);
+    }
+
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    public java.lang.String getReadonlyProperty() {
+        return this.jsiiGet("readonlyProperty", java.lang.String.class);
+    }
+
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    @javax.annotation.Nullable
+    public java.lang.Number getMutableProperty() {
+        return this.jsiiGet("mutableProperty", java.lang.Number.class);
+    }
+
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    public void setMutableProperty(@javax.annotation.Nullable final java.lang.Number value) {
+        this.jsiiSet("mutableProperty", value);
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StabilityTest.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalEnum.java
similarity index 51%
rename from packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StabilityTest.java
rename to packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalEnum.java
index 589f22a11c..068e43779e 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StabilityTest.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalEnum.java
@@ -1,25 +1,20 @@
 package software.amazon.jsii.tests.calculator;
 
 /**
- * This enum is there to test various stability levels are correctly emitted.
+ * EXPERIMENTAL
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
-@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
-@software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.StabilityTest")
-public enum StabilityTest {
-    /**
-     * @deprecated yeah this one's no good
-     */
-    @Deprecated
-    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
-    DeprecatedMember,
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+@software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.ExperimentalEnum")
+public enum ExperimentalEnum {
     /**
      * EXPERIMENTAL
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    ExperimentalMember,
+    OptionA,
     /**
+     * EXPERIMENTAL
      */
-    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
-    StableMember,
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    OptionB,
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalStruct.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalStruct.java
new file mode 100644
index 0000000000..0831739468
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalStruct.java
@@ -0,0 +1,84 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ * EXPERIMENTAL
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+public interface ExperimentalStruct extends software.amazon.jsii.JsiiSerializable {
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    java.lang.String getReadonlyProperty();
+
+    /**
+     * @return a {@link Builder} of {@link ExperimentalStruct}
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * A builder for {@link ExperimentalStruct}
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    final class Builder {
+        private java.lang.String _readonlyProperty;
+
+        /**
+         * Sets the value of ReadonlyProperty
+         * @param value the value to be set
+         * @return {@code this}
+         */
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        public Builder withReadonlyProperty(final java.lang.String value) {
+            this._readonlyProperty = java.util.Objects.requireNonNull(value, "readonlyProperty is required");
+            return this;
+        }
+
+        /**
+         * Builds the configured instance.
+         * @return a new instance of {@link ExperimentalStruct}
+         * @throws NullPointerException if any required attribute was not provided
+         */
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        public ExperimentalStruct build() {
+            return new ExperimentalStruct() {
+                private final java.lang.String $readonlyProperty = java.util.Objects.requireNonNull(_readonlyProperty, "readonlyProperty is required");
+
+                @Override
+                public java.lang.String getReadonlyProperty() {
+                    return this.$readonlyProperty;
+                }
+
+                public com.fasterxml.jackson.databind.JsonNode $jsii$toJson() {
+                    com.fasterxml.jackson.databind.ObjectMapper om = software.amazon.jsii.JsiiObjectMapper.INSTANCE;
+                    com.fasterxml.jackson.databind.node.ObjectNode obj = com.fasterxml.jackson.databind.node.JsonNodeFactory.instance.objectNode();
+                    obj.set("readonlyProperty", om.valueToTree(this.getReadonlyProperty()));
+                    return obj;
+                }
+
+            };
+        }
+    }
+
+    /**
+     * A proxy class which represents a concrete javascript instance of this type.
+     */
+    final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements software.amazon.jsii.tests.calculator.ExperimentalStruct {
+        protected Jsii$Proxy(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+            super(mode);
+        }
+
+        /**
+         * EXPERIMENTAL
+         */
+        @Override
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        public java.lang.String getReadonlyProperty() {
+            return this.jsiiGet("readonlyProperty", java.lang.String.class);
+        }
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IDeprecatedInterface.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IDeprecatedInterface.java
new file mode 100644
index 0000000000..7ad15eedf7
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IDeprecatedInterface.java
@@ -0,0 +1,66 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ * @deprecated for the show
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@Deprecated
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+public interface IDeprecatedInterface extends software.amazon.jsii.JsiiSerializable {
+    /**
+     * @deprecated for the show
+     */
+    @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+    java.lang.Number getMutableProperty();
+    /**
+     * @deprecated for the show
+     */
+    void setMutableProperty(final java.lang.Number value);
+    /**
+     * @deprecated for the show
+     */
+    @Deprecated
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+    void method();
+
+    /**
+     * A proxy class which represents a concrete javascript instance of this type.
+     */
+    final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements software.amazon.jsii.tests.calculator.IDeprecatedInterface {
+        protected Jsii$Proxy(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+            super(mode);
+        }
+
+        /**
+         * @deprecated for the show
+         */
+        @Override
+        @Deprecated
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+        @javax.annotation.Nullable
+        public java.lang.Number getMutableProperty() {
+            return this.jsiiGet("mutableProperty", java.lang.Number.class);
+        }
+
+        /**
+         * @deprecated for the show
+         */
+        @Override
+        @Deprecated
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+        public void setMutableProperty(@javax.annotation.Nullable final java.lang.Number value) {
+            this.jsiiSet("mutableProperty", value);
+        }
+
+        /**
+         * @deprecated for the show
+         */
+        @Deprecated
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
+        @Override
+        public void method() {
+            this.jsiiCall("method", Void.class);
+        }
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IExperimentalInterface.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IExperimentalInterface.java
new file mode 100644
index 0000000000..9b5e377dc5
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IExperimentalInterface.java
@@ -0,0 +1,60 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ * EXPERIMENTAL
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+public interface IExperimentalInterface extends software.amazon.jsii.JsiiSerializable {
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    java.lang.Number getMutableProperty();
+    /**
+     * EXPERIMENTAL
+     */
+    void setMutableProperty(final java.lang.Number value);
+    /**
+     * EXPERIMENTAL
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+    void method();
+
+    /**
+     * A proxy class which represents a concrete javascript instance of this type.
+     */
+    final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements software.amazon.jsii.tests.calculator.IExperimentalInterface {
+        protected Jsii$Proxy(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+            super(mode);
+        }
+
+        /**
+         * EXPERIMENTAL
+         */
+        @Override
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @javax.annotation.Nullable
+        public java.lang.Number getMutableProperty() {
+            return this.jsiiGet("mutableProperty", java.lang.Number.class);
+        }
+
+        /**
+         * EXPERIMENTAL
+         */
+        @Override
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        public void setMutableProperty(@javax.annotation.Nullable final java.lang.Number value) {
+            this.jsiiSet("mutableProperty", value);
+        }
+
+        /**
+         * EXPERIMENTAL
+         */
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
+        public void method() {
+            this.jsiiCall("method", Void.class);
+        }
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IStableInterface.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IStableInterface.java
new file mode 100644
index 0000000000..d83bb9d5d1
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IStableInterface.java
@@ -0,0 +1,53 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+public interface IStableInterface extends software.amazon.jsii.JsiiSerializable {
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    java.lang.Number getMutableProperty();
+    /**
+     */
+    void setMutableProperty(final java.lang.Number value);
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    void method();
+
+    /**
+     * A proxy class which represents a concrete javascript instance of this type.
+     */
+    final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements software.amazon.jsii.tests.calculator.IStableInterface {
+        protected Jsii$Proxy(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+            super(mode);
+        }
+
+        /**
+         */
+        @Override
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+        @javax.annotation.Nullable
+        public java.lang.Number getMutableProperty() {
+            return this.jsiiGet("mutableProperty", java.lang.Number.class);
+        }
+
+        /**
+         */
+        @Override
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+        public void setMutableProperty(@javax.annotation.Nullable final java.lang.Number value) {
+            this.jsiiSet("mutableProperty", value);
+        }
+
+        /**
+         */
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+        @Override
+        public void method() {
+            this.jsiiCall("method", Void.class);
+        }
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableClass.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableClass.java
new file mode 100644
index 0000000000..d45dd01205
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableClass.java
@@ -0,0 +1,55 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+@software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.StableClass")
+public class StableClass extends software.amazon.jsii.JsiiObject {
+    protected StableClass(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+        super(mode);
+    }
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    public StableClass(final java.lang.String readonlyString, @javax.annotation.Nullable final java.lang.Number mutableNumber) {
+        super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
+        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(readonlyString, "readonlyString is required"), mutableNumber });
+    }
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    public StableClass(final java.lang.String readonlyString) {
+        super(software.amazon.jsii.JsiiObject.InitializationMode.Jsii);
+        software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(readonlyString, "readonlyString is required") });
+    }
+
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    public void method() {
+        this.jsiiCall("method", Void.class);
+    }
+
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    public java.lang.String getReadonlyProperty() {
+        return this.jsiiGet("readonlyProperty", java.lang.String.class);
+    }
+
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    @javax.annotation.Nullable
+    public java.lang.Number getMutableProperty() {
+        return this.jsiiGet("mutableProperty", java.lang.Number.class);
+    }
+
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    public void setMutableProperty(@javax.annotation.Nullable final java.lang.Number value) {
+        this.jsiiSet("mutableProperty", value);
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableEnum.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableEnum.java
new file mode 100644
index 0000000000..a150455ab7
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableEnum.java
@@ -0,0 +1,17 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+@software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.StableEnum")
+public enum StableEnum {
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    OptionA,
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    OptionB,
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableStruct.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableStruct.java
new file mode 100644
index 0000000000..96642436cb
--- /dev/null
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/StableStruct.java
@@ -0,0 +1,81 @@
+package software.amazon.jsii.tests.calculator;
+
+/**
+ */
+@javax.annotation.Generated(value = "jsii-pacmak")
+@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+public interface StableStruct extends software.amazon.jsii.JsiiSerializable {
+    /**
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    java.lang.String getReadonlyProperty();
+
+    /**
+     * @return a {@link Builder} of {@link StableStruct}
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * A builder for {@link StableStruct}
+     */
+    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+    final class Builder {
+        private java.lang.String _readonlyProperty;
+
+        /**
+         * Sets the value of ReadonlyProperty
+         * @param value the value to be set
+         * @return {@code this}
+         */
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+        public Builder withReadonlyProperty(final java.lang.String value) {
+            this._readonlyProperty = java.util.Objects.requireNonNull(value, "readonlyProperty is required");
+            return this;
+        }
+
+        /**
+         * Builds the configured instance.
+         * @return a new instance of {@link StableStruct}
+         * @throws NullPointerException if any required attribute was not provided
+         */
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+        public StableStruct build() {
+            return new StableStruct() {
+                private final java.lang.String $readonlyProperty = java.util.Objects.requireNonNull(_readonlyProperty, "readonlyProperty is required");
+
+                @Override
+                public java.lang.String getReadonlyProperty() {
+                    return this.$readonlyProperty;
+                }
+
+                public com.fasterxml.jackson.databind.JsonNode $jsii$toJson() {
+                    com.fasterxml.jackson.databind.ObjectMapper om = software.amazon.jsii.JsiiObjectMapper.INSTANCE;
+                    com.fasterxml.jackson.databind.node.ObjectNode obj = com.fasterxml.jackson.databind.node.JsonNodeFactory.instance.objectNode();
+                    obj.set("readonlyProperty", om.valueToTree(this.getReadonlyProperty()));
+                    return obj;
+                }
+
+            };
+        }
+    }
+
+    /**
+     * A proxy class which represents a concrete javascript instance of this type.
+     */
+    final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements software.amazon.jsii.tests.calculator.StableStruct {
+        protected Jsii$Proxy(final software.amazon.jsii.JsiiObject.InitializationMode mode) {
+            super(mode);
+        }
+
+        /**
+         */
+        @Override
+        @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
+        public java.lang.String getReadonlyProperty() {
+            return this.jsiiGet("readonlyProperty", java.lang.String.class);
+        }
+    }
+}
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py b/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
index f29e2608a6..15f8b398a2 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
@@ -550,66 +550,110 @@ def arg2(self) -> typing.Optional[str]:
 
 
 class DeprecatedClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.DeprecatedClass"):
-    """This tests code generation of deprecation markers.
-
+    """
     Deprecated:
-        without replacement
+        for the show
 
     Stability:
         deprecated
     """
-    def __init__(self, argument: typing.Optional[str]=None) -> None:
+    def __init__(self, readonly_string: str, mutable_number: typing.Optional[jsii.Number]=None) -> None:
         """
         Arguments:
-            argument: some string.
+            readonlyString: -
+            mutableNumber: -
 
         Deprecated:
-            this is unsafe
+            for the show
 
         Stability:
             deprecated
         """
-        jsii.create(DeprecatedClass, self, [argument])
+        jsii.create(DeprecatedClass, self, [readonly_string, mutable_number])
 
-    @jsii.member(jsii_name="deprecatedMethod")
-    def deprecated_method(self) -> None:
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
         """
         Deprecated:
-            throws unexpected errors
+            for the show
 
         Stability:
             deprecated
         """
-        return jsii.invoke(self, "deprecatedMethod", [])
+        return jsii.invoke(self, "method", [])
 
     @property
-    @jsii.member(jsii_name="deprecatedAttribute")
-    def deprecated_attribute(self) -> str:
+    @jsii.member(jsii_name="readonlyProperty")
+    def readonly_property(self) -> str:
         """
         Deprecated:
-            intentionally
+            for the show
 
         Stability:
             deprecated
         """
-        return jsii.get(self, "deprecatedAttribute")
+        return jsii.get(self, "readonlyProperty")
 
     @property
-    @jsii.member(jsii_name="deprecatedProtected")
-    def _deprecated_protected(self) -> typing.Optional[str]:
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
         """
         Deprecated:
-            can be unexpectedly non-null!
+            for the show
 
         Stability:
             deprecated
         """
-        return jsii.get(self, "deprecatedProtected")
+        return jsii.get(self, "mutableProperty")
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        return jsii.set(self, "mutableProperty", value)
+
+
+@jsii.enum(jsii_type="jsii-calc.DeprecatedEnum")
+class DeprecatedEnum(enum.Enum):
+    """
+    Deprecated:
+        for the show
+
+    Stability:
+        deprecated
+    """
+    OptionA = "OptionA"
+    """
+    Deprecated:
+        for the show
 
-    @_deprecated_protected.setter
-    def _deprecated_protected(self, value: typing.Optional[str]):
-        return jsii.set(self, "deprecatedProtected", value)
+    Stability:
+        deprecated
+    """
+    OptionB = "OptionB"
+    """
+    Deprecated:
+        for the show
+
+    Stability:
+        deprecated
+    """
+
+@jsii.data_type(jsii_type="jsii-calc.DeprecatedStruct", jsii_struct_bases=[])
+class DeprecatedStruct(jsii.compat.TypedDict):
+    """
+    Deprecated:
+        for the show
+
+    Stability:
+        deprecated
+    """
+    readonlyProperty: str
+    """
+    Deprecated:
+        for the show
 
+    Stability:
+        deprecated
+    """
 
 class DerivedClassHasNoProperties:
     class Base(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.DerivedClassHasNoProperties.Base"):
@@ -782,6 +826,82 @@ class EraseUndefinedHashValuesOptions(jsii.compat.TypedDict, total=False):
 
     option2: str
 
+class ExperimentalClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.ExperimentalClass"):
+    """
+    Stability:
+        experimental
+    """
+    def __init__(self, readonly_string: str, mutable_number: typing.Optional[jsii.Number]=None) -> None:
+        """
+        Arguments:
+            readonlyString: -
+            mutableNumber: -
+
+        Stability:
+            experimental
+        """
+        jsii.create(ExperimentalClass, self, [readonly_string, mutable_number])
+
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
+        """
+        Stability:
+            experimental
+        """
+        return jsii.invoke(self, "method", [])
+
+    @property
+    @jsii.member(jsii_name="readonlyProperty")
+    def readonly_property(self) -> str:
+        """
+        Stability:
+            experimental
+        """
+        return jsii.get(self, "readonlyProperty")
+
+    @property
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
+        """
+        Stability:
+            experimental
+        """
+        return jsii.get(self, "mutableProperty")
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        return jsii.set(self, "mutableProperty", value)
+
+
+@jsii.enum(jsii_type="jsii-calc.ExperimentalEnum")
+class ExperimentalEnum(enum.Enum):
+    """
+    Stability:
+        experimental
+    """
+    OptionA = "OptionA"
+    """
+    Stability:
+        experimental
+    """
+    OptionB = "OptionB"
+    """
+    Stability:
+        experimental
+    """
+
+@jsii.data_type(jsii_type="jsii-calc.ExperimentalStruct", jsii_struct_bases=[])
+class ExperimentalStruct(jsii.compat.TypedDict):
+    """
+    Stability:
+        experimental
+    """
+    readonlyProperty: str
+    """
+    Stability:
+        experimental
+    """
+
 class ExportedBaseClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.ExportedBaseClass"):
     def __init__(self, success: bool) -> None:
         """
@@ -944,6 +1064,144 @@ def a(self, value: str):
         return jsii.set(self, "a", value)
 
 
+@jsii.interface(jsii_type="jsii-calc.IDeprecatedInterface")
+class IDeprecatedInterface(jsii.compat.Protocol):
+    """
+    Deprecated:
+        for the show
+
+    Stability:
+        deprecated
+    """
+    @staticmethod
+    def __jsii_proxy_class__():
+        return _IDeprecatedInterfaceProxy
+
+    @property
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
+        """
+        Deprecated:
+            for the show
+
+        Stability:
+            deprecated
+        """
+        ...
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        ...
+
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
+        """
+        Deprecated:
+            for the show
+
+        Stability:
+            deprecated
+        """
+        ...
+
+
+class _IDeprecatedInterfaceProxy():
+    """
+    Deprecated:
+        for the show
+
+    Stability:
+        deprecated
+    """
+    __jsii_type__ = "jsii-calc.IDeprecatedInterface"
+    @property
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
+        """
+        Deprecated:
+            for the show
+
+        Stability:
+            deprecated
+        """
+        return jsii.get(self, "mutableProperty")
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        return jsii.set(self, "mutableProperty", value)
+
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
+        """
+        Deprecated:
+            for the show
+
+        Stability:
+            deprecated
+        """
+        return jsii.invoke(self, "method", [])
+
+
+@jsii.interface(jsii_type="jsii-calc.IExperimentalInterface")
+class IExperimentalInterface(jsii.compat.Protocol):
+    """
+    Stability:
+        experimental
+    """
+    @staticmethod
+    def __jsii_proxy_class__():
+        return _IExperimentalInterfaceProxy
+
+    @property
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
+        """
+        Stability:
+            experimental
+        """
+        ...
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        ...
+
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
+        """
+        Stability:
+            experimental
+        """
+        ...
+
+
+class _IExperimentalInterfaceProxy():
+    """
+    Stability:
+        experimental
+    """
+    __jsii_type__ = "jsii-calc.IExperimentalInterface"
+    @property
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
+        """
+        Stability:
+            experimental
+        """
+        return jsii.get(self, "mutableProperty")
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        return jsii.set(self, "mutableProperty", value)
+
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
+        """
+        Stability:
+            experimental
+        """
+        return jsii.invoke(self, "method", [])
+
+
 @jsii.interface(jsii_type="jsii-calc.IExtendsPrivateInterface")
 class IExtendsPrivateInterface(jsii.compat.Protocol):
     @staticmethod
@@ -1674,6 +1932,66 @@ def obtain_number(self) -> scope.jsii_calc_lib.IDoublable:
         return jsii.invoke(self, "obtainNumber", [])
 
 
+@jsii.interface(jsii_type="jsii-calc.IStableInterface")
+class IStableInterface(jsii.compat.Protocol):
+    """
+    Stability:
+        stable
+    """
+    @staticmethod
+    def __jsii_proxy_class__():
+        return _IStableInterfaceProxy
+
+    @property
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
+        """
+        Stability:
+            stable
+        """
+        ...
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        ...
+
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
+        """
+        Stability:
+            stable
+        """
+        ...
+
+
+class _IStableInterfaceProxy():
+    """
+    Stability:
+        stable
+    """
+    __jsii_type__ = "jsii-calc.IStableInterface"
+    @property
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
+        """
+        Stability:
+            stable
+        """
+        return jsii.get(self, "mutableProperty")
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        return jsii.set(self, "mutableProperty", value)
+
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
+        """
+        Stability:
+            stable
+        """
+        return jsii.invoke(self, "method", [])
+
+
 class ImplementInternalInterface(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.ImplementInternalInterface"):
     def __init__(self) -> None:
         jsii.create(ImplementInternalInterface, self, [])
@@ -2705,27 +3023,77 @@ def interface2(self) -> "IPublicInterface":
         return jsii.invoke(self, "interface2", [])
 
 
-@jsii.enum(jsii_type="jsii-calc.StabilityTest")
-class StabilityTest(enum.Enum):
-    """This enum is there to test various stability levels are correctly emitted.
+class StableClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.StableClass"):
+    """
+    Stability:
+        stable
+    """
+    def __init__(self, readonly_string: str, mutable_number: typing.Optional[jsii.Number]=None) -> None:
+        """
+        Arguments:
+            readonlyString: -
+            mutableNumber: -
 
+        Stability:
+            stable
+        """
+        jsii.create(StableClass, self, [readonly_string, mutable_number])
+
+    @jsii.member(jsii_name="method")
+    def method(self) -> None:
+        """
+        Stability:
+            stable
+        """
+        return jsii.invoke(self, "method", [])
+
+    @property
+    @jsii.member(jsii_name="readonlyProperty")
+    def readonly_property(self) -> str:
+        """
+        Stability:
+            stable
+        """
+        return jsii.get(self, "readonlyProperty")
+
+    @property
+    @jsii.member(jsii_name="mutableProperty")
+    def mutable_property(self) -> typing.Optional[jsii.Number]:
+        """
+        Stability:
+            stable
+        """
+        return jsii.get(self, "mutableProperty")
+
+    @mutable_property.setter
+    def mutable_property(self, value: typing.Optional[jsii.Number]):
+        return jsii.set(self, "mutableProperty", value)
+
+
+@jsii.enum(jsii_type="jsii-calc.StableEnum")
+class StableEnum(enum.Enum):
+    """
     Stability:
         stable
     """
-    DeprecatedMember = "DeprecatedMember"
+    OptionA = "OptionA"
     """
-    Deprecated:
-        yeah this one's no good
-
     Stability:
-        deprecated
+        stable
     """
-    ExperimentalMember = "ExperimentalMember"
+    OptionB = "OptionB"
     """
     Stability:
-        experimental
+        stable
+    """
+
+@jsii.data_type(jsii_type="jsii-calc.StableStruct", jsii_struct_bases=[])
+class StableStruct(jsii.compat.TypedDict):
+    """
+    Stability:
+        stable
     """
-    StableMember = "StableMember"
+    readonlyProperty: str
     """
     Stability:
         stable
@@ -3413,6 +3781,6 @@ def parts(self, value: typing.List[scope.jsii_calc_lib.Value]):
         return jsii.set(self, "parts", value)
 
 
-__all__ = ["AbstractClass", "AbstractClassBase", "AbstractClassReturner", "Add", "AllTypes", "AllTypesEnum", "AllowedMethodNames", "AsyncVirtualMethods", "AugmentableClass", "BinaryOperation", "Calculator", "CalculatorProps", "ClassThatImplementsTheInternalInterface", "ClassThatImplementsThePrivateInterface", "ClassWithDocs", "ClassWithMutableObjectLiteralProperty", "ClassWithPrivateConstructorAndAutomaticProperties", "ConstructorPassesThisOut", "Constructors", "ConsumersOfThisCrazyTypeSystem", "DefaultedConstructorArgument", "DeprecatedClass", "DerivedClassHasNoProperties", "DerivedStruct", "DoNotOverridePrivates", "DoNotRecognizeAnyAsOptional", "DocumentedClass", "DontComplainAboutVariadicAfterOptional", "DoubleTrouble", "EraseUndefinedHashValues", "EraseUndefinedHashValuesOptions", "ExportedBaseClass", "ExtendsInternalInterface", "GiveMeStructs", "Greetee", "GreetingAugmenter", "IAnotherPublicInterface", "IExtendsPrivateInterface", "IFriendlier", "IFriendlyRandomGenerator", "IInterfaceImplementedByAbstractClass", "IInterfaceThatShouldNotBeADataType", "IInterfaceWithInternal", "IInterfaceWithMethods", "IInterfaceWithOptionalMethodArguments", "IInterfaceWithProperties", "IInterfaceWithPropertiesExtension", "IJSII417Derived", "IJSII417PublicBaseOfBase", "IJsii487External", "IJsii487External2", "IJsii496", "IMutableObjectLiteral", "INonInternalInterface", "IPrivatelyImplemented", "IPublicInterface", "IPublicInterface2", "IRandomNumberGenerator", "IReturnsNumber", "ImplementInternalInterface", "ImplementsInterfaceWithInternal", "ImplementsInterfaceWithInternalSubclass", "ImplementsPrivateInterface", "ImplictBaseOfBase", "InbetweenClass", "InterfaceInNamespaceIncludesClasses", "InterfaceInNamespaceOnlyInterface", "JSII417Derived", "JSII417PublicBaseOfBase", "JSObjectLiteralForInterface", "JSObjectLiteralToNative", "JSObjectLiteralToNativeClass", "JavaReservedWords", "Jsii487Derived", "Jsii496Derived", "JsiiAgent", "LoadBalancedFargateServiceProps", "Multiply", "Negate", "NodeStandardLibrary", "NullShouldBeTreatedAsUndefined", "NullShouldBeTreatedAsUndefinedData", "NumberGenerator", "ObjectRefsInCollections", "Old", "OptionalConstructorArgument", "OptionalStruct", "OptionalStructConsumer", "OverrideReturnsObject", "PartiallyInitializedThisConsumer", "Polymorphism", "Power", "PublicClass", "PythonReservedWords", "ReferenceEnumFromScopedPackage", "ReturnsPrivateImplementationOfInterface", "RuntimeTypeChecking", "SingleInstanceTwoTypes", "StabilityTest", "StaticContext", "Statics", "StringEnum", "StripInternal", "Sum", "SyncVirtualMethods", "Thrower", "UnaryOperation", "UnionProperties", "UseBundledDependency", "UseCalcBase", "UsesInterfaceWithProperties", "VariadicMethod", "VirtualMethodPlayground", "VoidCallback", "__jsii_assembly__", "composition"]
+__all__ = ["AbstractClass", "AbstractClassBase", "AbstractClassReturner", "Add", "AllTypes", "AllTypesEnum", "AllowedMethodNames", "AsyncVirtualMethods", "AugmentableClass", "BinaryOperation", "Calculator", "CalculatorProps", "ClassThatImplementsTheInternalInterface", "ClassThatImplementsThePrivateInterface", "ClassWithDocs", "ClassWithMutableObjectLiteralProperty", "ClassWithPrivateConstructorAndAutomaticProperties", "ConstructorPassesThisOut", "Constructors", "ConsumersOfThisCrazyTypeSystem", "DefaultedConstructorArgument", "DeprecatedClass", "DeprecatedEnum", "DeprecatedStruct", "DerivedClassHasNoProperties", "DerivedStruct", "DoNotOverridePrivates", "DoNotRecognizeAnyAsOptional", "DocumentedClass", "DontComplainAboutVariadicAfterOptional", "DoubleTrouble", "EraseUndefinedHashValues", "EraseUndefinedHashValuesOptions", "ExperimentalClass", "ExperimentalEnum", "ExperimentalStruct", "ExportedBaseClass", "ExtendsInternalInterface", "GiveMeStructs", "Greetee", "GreetingAugmenter", "IAnotherPublicInterface", "IDeprecatedInterface", "IExperimentalInterface", "IExtendsPrivateInterface", "IFriendlier", "IFriendlyRandomGenerator", "IInterfaceImplementedByAbstractClass", "IInterfaceThatShouldNotBeADataType", "IInterfaceWithInternal", "IInterfaceWithMethods", "IInterfaceWithOptionalMethodArguments", "IInterfaceWithProperties", "IInterfaceWithPropertiesExtension", "IJSII417Derived", "IJSII417PublicBaseOfBase", "IJsii487External", "IJsii487External2", "IJsii496", "IMutableObjectLiteral", "INonInternalInterface", "IPrivatelyImplemented", "IPublicInterface", "IPublicInterface2", "IRandomNumberGenerator", "IReturnsNumber", "IStableInterface", "ImplementInternalInterface", "ImplementsInterfaceWithInternal", "ImplementsInterfaceWithInternalSubclass", "ImplementsPrivateInterface", "ImplictBaseOfBase", "InbetweenClass", "InterfaceInNamespaceIncludesClasses", "InterfaceInNamespaceOnlyInterface", "JSII417Derived", "JSII417PublicBaseOfBase", "JSObjectLiteralForInterface", "JSObjectLiteralToNative", "JSObjectLiteralToNativeClass", "JavaReservedWords", "Jsii487Derived", "Jsii496Derived", "JsiiAgent", "LoadBalancedFargateServiceProps", "Multiply", "Negate", "NodeStandardLibrary", "NullShouldBeTreatedAsUndefined", "NullShouldBeTreatedAsUndefinedData", "NumberGenerator", "ObjectRefsInCollections", "Old", "OptionalConstructorArgument", "OptionalStruct", "OptionalStructConsumer", "OverrideReturnsObject", "PartiallyInitializedThisConsumer", "Polymorphism", "Power", "PublicClass", "PythonReservedWords", "ReferenceEnumFromScopedPackage", "ReturnsPrivateImplementationOfInterface", "RuntimeTypeChecking", "SingleInstanceTwoTypes", "StableClass", "StableEnum", "StableStruct", "StaticContext", "Statics", "StringEnum", "StripInternal", "Sum", "SyncVirtualMethods", "Thrower", "UnaryOperation", "UnionProperties", "UseBundledDependency", "UseCalcBase", "UsesInterfaceWithProperties", "VariadicMethod", "VirtualMethodPlayground", "VoidCallback", "__jsii_assembly__", "composition"]
 
 publication.publish()
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
index 3d1b07a0cb..b53b3269c7 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
@@ -1492,7 +1492,7 @@ DefaultedConstructorArgument
 DeprecatedClass
 ^^^^^^^^^^^^^^^
 
-.. py:class:: DeprecatedClass([argument])
+.. py:class:: DeprecatedClass(readonlyString, [mutableNumber])
 
    **Language-specific names:**
 
@@ -1516,27 +1516,89 @@ DeprecatedClass
 
 
 
-   This tests code generation of deprecation markers.
+   :param readonlyString: 
+   :type readonlyString: string
+   :param mutableNumber: 
+   :type mutableNumber: number
 
+   .. py:method:: method()
 
 
-   :param argument: some string.
-   :type argument: string
 
-   .. py:method:: deprecatedMethod()
+   .. py:attribute:: readonlyProperty
 
+      :type: string *(readonly)*
 
 
-   .. py:attribute:: deprecatedAttribute
+   .. py:attribute:: mutableProperty
+
+      :type: number *(optional)*
 
-      :type: string *(readonly)*
 
+DeprecatedEnum (enum)
+^^^^^^^^^^^^^^^^^^^^^
 
-   .. py:attribute:: deprecatedProtected
+.. py:class:: DeprecatedEnum
 
-      *Protected property*
+   **Language-specific names:**
 
-      :type: string *(optional)*
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.DeprecatedEnum;
+
+      .. code-tab:: javascript
+
+         const { DeprecatedEnum } = require('jsii-calc');
+
+      .. code-tab:: typescript
+
+         import { DeprecatedEnum } from 'jsii-calc';
+
+
+
+   .. py:data:: OptionA
+
+   .. py:data:: OptionB
+
+
+DeprecatedStruct (interface)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:class:: DeprecatedStruct
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.DeprecatedStruct;
+
+      .. code-tab:: javascript
+
+         // DeprecatedStruct is an interface
+
+      .. code-tab:: typescript
+
+         import { DeprecatedStruct } from 'jsii-calc';
+
+
+
+
+
+   .. py:attribute:: readonlyProperty
+
+      :type: string *(readonly)*
 
 
 
@@ -2063,6 +2125,118 @@ EraseUndefinedHashValuesOptions (interface)
       :type: string *(optional)* *(readonly)*
 
 
+ExperimentalClass
+^^^^^^^^^^^^^^^^^
+
+.. py:class:: ExperimentalClass(readonlyString, [mutableNumber])
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.ExperimentalClass;
+
+      .. code-tab:: javascript
+
+         const { ExperimentalClass } = require('jsii-calc');
+
+      .. code-tab:: typescript
+
+         import { ExperimentalClass } from 'jsii-calc';
+
+
+
+   :param readonlyString: 
+   :type readonlyString: string
+   :param mutableNumber: 
+   :type mutableNumber: number
+
+   .. py:method:: method()
+
+
+
+   .. py:attribute:: readonlyProperty
+
+      :type: string *(readonly)*
+
+
+   .. py:attribute:: mutableProperty
+
+      :type: number *(optional)*
+
+
+ExperimentalEnum (enum)
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:class:: ExperimentalEnum
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.ExperimentalEnum;
+
+      .. code-tab:: javascript
+
+         const { ExperimentalEnum } = require('jsii-calc');
+
+      .. code-tab:: typescript
+
+         import { ExperimentalEnum } from 'jsii-calc';
+
+
+
+   .. py:data:: OptionA
+
+   .. py:data:: OptionB
+
+
+ExperimentalStruct (interface)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:class:: ExperimentalStruct
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.ExperimentalStruct;
+
+      .. code-tab:: javascript
+
+         // ExperimentalStruct is an interface
+
+      .. code-tab:: typescript
+
+         import { ExperimentalStruct } from 'jsii-calc';
+
+
+
+
+
+   .. py:attribute:: readonlyProperty
+
+      :type: string *(readonly)*
+
+
 ExportedBaseClass
 ^^^^^^^^^^^^^^^^^
 
@@ -2315,6 +2489,84 @@ IAnotherPublicInterface (interface)
       :type: string
 
 
+IDeprecatedInterface (interface)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:class:: IDeprecatedInterface
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.IDeprecatedInterface;
+
+      .. code-tab:: javascript
+
+         // IDeprecatedInterface is an interface
+
+      .. code-tab:: typescript
+
+         import { IDeprecatedInterface } from 'jsii-calc';
+
+
+
+
+
+   .. py:attribute:: mutableProperty
+
+      :type: number *(optional)*
+
+
+   .. py:method:: method()
+
+      :abstract: Yes
+
+
+IExperimentalInterface (interface)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:class:: IExperimentalInterface
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.IExperimentalInterface;
+
+      .. code-tab:: javascript
+
+         // IExperimentalInterface is an interface
+
+      .. code-tab:: typescript
+
+         import { IExperimentalInterface } from 'jsii-calc';
+
+
+
+
+
+   .. py:attribute:: mutableProperty
+
+      :type: number *(optional)*
+
+
+   .. py:method:: method()
+
+      :abstract: Yes
+
+
 IExtendsPrivateInterface (interface)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -3225,6 +3477,45 @@ IReturnsNumber (interface)
       :abstract: Yes
 
 
+IStableInterface (interface)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:class:: IStableInterface
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.IStableInterface;
+
+      .. code-tab:: javascript
+
+         // IStableInterface is an interface
+
+      .. code-tab:: typescript
+
+         import { IStableInterface } from 'jsii-calc';
+
+
+
+
+
+   .. py:attribute:: mutableProperty
+
+      :type: number *(optional)*
+
+
+   .. py:method:: method()
+
+      :abstract: Yes
+
+
 ImplementInternalInterface
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -5540,10 +5831,10 @@ SingleInstanceTwoTypes
       :rtype: :py:class:`~jsii-calc.IPublicInterface`\ 
 
 
-StabilityTest (enum)
-^^^^^^^^^^^^^^^^^^^^
+StableClass
+^^^^^^^^^^^
 
-.. py:class:: StabilityTest
+.. py:class:: StableClass(readonlyString, [mutableNumber])
 
    **Language-specific names:**
 
@@ -5555,27 +5846,101 @@ StabilityTest (enum)
 
       .. code-tab:: java
 
-         import software.amazon.jsii.tests.calculator.StabilityTest;
+         import software.amazon.jsii.tests.calculator.StableClass;
 
       .. code-tab:: javascript
 
-         const { StabilityTest } = require('jsii-calc');
+         const { StableClass } = require('jsii-calc');
 
       .. code-tab:: typescript
 
-         import { StabilityTest } from 'jsii-calc';
+         import { StableClass } from 'jsii-calc';
+
+
+
+   :param readonlyString: 
+   :type readonlyString: string
+   :param mutableNumber: 
+   :type mutableNumber: number
+
+   .. py:method:: method()
 
 
 
-   This enum is there to test various stability levels are correctly emitted.
+   .. py:attribute:: readonlyProperty
+
+      :type: string *(readonly)*
+
+
+   .. py:attribute:: mutableProperty
 
+      :type: number *(optional)*
 
 
-   .. py:data:: DeprecatedMember
+StableEnum (enum)
+^^^^^^^^^^^^^^^^^
 
-   .. py:data:: ExperimentalMember
+.. py:class:: StableEnum
 
-   .. py:data:: StableMember
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.StableEnum;
+
+      .. code-tab:: javascript
+
+         const { StableEnum } = require('jsii-calc');
+
+      .. code-tab:: typescript
+
+         import { StableEnum } from 'jsii-calc';
+
+
+
+   .. py:data:: OptionA
+
+   .. py:data:: OptionB
+
+
+StableStruct (interface)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:class:: StableStruct
+
+   **Language-specific names:**
+
+   .. tabs::
+
+      .. code-tab:: c#
+
+         using Amazon.JSII.Tests.CalculatorNamespace;
+
+      .. code-tab:: java
+
+         import software.amazon.jsii.tests.calculator.StableStruct;
+
+      .. code-tab:: javascript
+
+         // StableStruct is an interface
+
+      .. code-tab:: typescript
+
+         import { StableStruct } from 'jsii-calc';
+
+
+
+
+
+   .. py:attribute:: readonlyProperty
+
+      :type: string *(readonly)*
 
 
 StaticContext
diff --git a/packages/jsii-reflect/test/classes.expected.txt b/packages/jsii-reflect/test/classes.expected.txt
index 6345821969..2c2e244197 100644
--- a/packages/jsii-reflect/test/classes.expected.txt
+++ b/packages/jsii-reflect/test/classes.expected.txt
@@ -28,6 +28,7 @@ DocumentedClass
 DontComplainAboutVariadicAfterOptional
 DoubleTrouble
 EraseUndefinedHashValues
+ExperimentalClass
 ExportedBaseClass
 Foo
 GiveMeStructs
@@ -67,6 +68,7 @@ ReferenceEnumFromScopedPackage
 ReturnsPrivateImplementationOfInterface
 RuntimeTypeChecking
 SingleInstanceTwoTypes
+StableClass
 StaticContext
 Statics
 StripInternal
diff --git a/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
index ca5814f53c..559508bb05 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.all.expected.txt
@@ -333,18 +333,19 @@ assemblies
  │   │     └── type: Optional<string>
  │   ├─┬ class DeprecatedClass
  │   │ └─┬ members
- │   │   ├─┬ <initializer>(argument) initializer
+ │   │   ├─┬ <initializer>(readonlyString,mutableNumber) initializer
  │   │   │ └─┬ parameters
- │   │   │   └─┬ argument
- │   │   │     └── type: Optional<string>
- │   │   ├─┬ deprecatedMethod() method
+ │   │   │   ├─┬ readonlyString
+ │   │   │   │ └── type: string
+ │   │   │   └─┬ mutableNumber
+ │   │   │     └── type: Optional<number>
+ │   │   ├─┬ method() method
  │   │   │ └── returns: void
- │   │   ├─┬ deprecatedAttribute property
+ │   │   ├─┬ readonlyProperty property
  │   │   │ ├── immutable
  │   │   │ └── type: string
- │   │   └─┬ deprecatedProtected property
- │   │     ├── protected
- │   │     └── type: Optional<string>
+ │   │   └─┬ mutableProperty property
+ │   │     └── type: Optional<number>
  │   ├─┬ class Base
  │   │ └─┬ members
  │   │   ├── <initializer>() initializer
@@ -425,6 +426,21 @@ assemblies
  │   │   └─┬ prop2IsUndefined() method
  │   │     ├── static
  │   │     └── returns: any
+ │   ├─┬ class ExperimentalClass
+ │   │ └─┬ members
+ │   │   ├─┬ <initializer>(readonlyString,mutableNumber) initializer
+ │   │   │ └─┬ parameters
+ │   │   │   ├─┬ readonlyString
+ │   │   │   │ └── type: string
+ │   │   │   └─┬ mutableNumber
+ │   │   │     └── type: Optional<number>
+ │   │   ├─┬ method() method
+ │   │   │ └── returns: void
+ │   │   ├─┬ readonlyProperty property
+ │   │   │ ├── immutable
+ │   │   │ └── type: string
+ │   │   └─┬ mutableProperty property
+ │   │     └── type: Optional<number>
  │   ├─┬ class ExportedBaseClass
  │   │ └─┬ members
  │   │   ├─┬ <initializer>(success) initializer
@@ -972,6 +988,21 @@ assemblies
  │   │   │ └── returns: jsii-calc.InbetweenClass
  │   │   └─┬ interface2() method
  │   │     └── returns: jsii-calc.IPublicInterface
+ │   ├─┬ class StableClass
+ │   │ └─┬ members
+ │   │   ├─┬ <initializer>(readonlyString,mutableNumber) initializer
+ │   │   │ └─┬ parameters
+ │   │   │   ├─┬ readonlyString
+ │   │   │   │ └── type: string
+ │   │   │   └─┬ mutableNumber
+ │   │   │     └── type: Optional<number>
+ │   │   ├─┬ method() method
+ │   │   │ └── returns: void
+ │   │   ├─┬ readonlyProperty property
+ │   │   │ ├── immutable
+ │   │   │ └── type: string
+ │   │   └─┬ mutableProperty property
+ │   │     └── type: Optional<number>
  │   ├─┬ class StaticContext
  │   │ └─┬ members
  │   │   ├─┬ canAccessStaticContext() method
@@ -1217,6 +1248,12 @@ assemblies
  │   │     ├── abstract
  │   │     ├── immutable
  │   │     └── type: Optional<number>
+ │   ├─┬ interface DeprecatedStruct
+ │   │ └─┬ members
+ │   │   └─┬ readonlyProperty property
+ │   │     ├── abstract
+ │   │     ├── immutable
+ │   │     └── type: string
  │   ├─┬ interface DerivedStruct
  │   │ ├─┬ interfaces
  │   │ │ └── MyFirstStruct
@@ -1255,6 +1292,12 @@ assemblies
  │   │     ├── abstract
  │   │     ├── immutable
  │   │     └── type: Optional<string>
+ │   ├─┬ interface ExperimentalStruct
+ │   │ └─┬ members
+ │   │   └─┬ readonlyProperty property
+ │   │     ├── abstract
+ │   │     ├── immutable
+ │   │     └── type: string
  │   ├─┬ interface ExtendsInternalInterface
  │   │ └─┬ members
  │   │   ├─┬ boom property
@@ -1276,6 +1319,22 @@ assemblies
  │   │   └─┬ a property
  │   │     ├── abstract
  │   │     └── type: string
+ │   ├─┬ interface IDeprecatedInterface
+ │   │ └─┬ members
+ │   │   ├─┬ method() method
+ │   │   │ ├── abstract
+ │   │   │ └── returns: void
+ │   │   └─┬ mutableProperty property
+ │   │     ├── abstract
+ │   │     └── type: Optional<number>
+ │   ├─┬ interface IExperimentalInterface
+ │   │ └─┬ members
+ │   │   ├─┬ method() method
+ │   │   │ ├── abstract
+ │   │   │ └── returns: void
+ │   │   └─┬ mutableProperty property
+ │   │     ├── abstract
+ │   │     └── type: Optional<number>
  │   ├─┬ interface IExtendsPrivateInterface
  │   │ └─┬ members
  │   │   ├─┬ moreThings property
@@ -1428,6 +1487,14 @@ assemblies
  │   │     ├── abstract
  │   │     ├── immutable
  │   │     └── type: @scope/jsii-calc-lib.Number
+ │   ├─┬ interface IStableInterface
+ │   │ └─┬ members
+ │   │   ├─┬ method() method
+ │   │   │ ├── abstract
+ │   │   │ └── returns: void
+ │   │   └─┬ mutableProperty property
+ │   │     ├── abstract
+ │   │     └── type: Optional<number>
  │   ├─┬ interface ImplictBaseOfBase
  │   │ ├─┬ interfaces
  │   │ │ └── BaseProps
@@ -1486,6 +1553,12 @@ assemblies
  │   │     ├── abstract
  │   │     ├── immutable
  │   │     └── type: Optional<string>
+ │   ├─┬ interface StableStruct
+ │   │ └─┬ members
+ │   │   └─┬ readonlyProperty property
+ │   │     ├── abstract
+ │   │     ├── immutable
+ │   │     └── type: string
  │   ├─┬ interface UnionProperties
  │   │ └─┬ members
  │   │   ├─┬ bar property
@@ -1500,10 +1573,15 @@ assemblies
  │   │ ├── MyEnumValue
  │   │ ├── YourEnumValue
  │   │ └── ThisIsGreat
- │   ├─┬ enum StabilityTest
- │   │ ├── DeprecatedMember
- │   │ ├── ExperimentalMember
- │   │ └── StableMember
+ │   ├─┬ enum DeprecatedEnum
+ │   │ ├── OptionA
+ │   │ └── OptionB
+ │   ├─┬ enum ExperimentalEnum
+ │   │ ├── OptionA
+ │   │ └── OptionB
+ │   ├─┬ enum StableEnum
+ │   │ ├── OptionA
+ │   │ └── OptionB
  │   ├─┬ enum StringEnum
  │   │ ├── A
  │   │ ├── B
diff --git a/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
index bc977cb445..5c30a6e070 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.inheritance.expected.txt
@@ -40,6 +40,7 @@ assemblies
  │   ├─┬ class DoubleTrouble
  │   │ └── interfaces: IFriendlyRandomGenerator
  │   ├── class EraseUndefinedHashValues
+ │   ├── class ExperimentalClass
  │   ├── class ExportedBaseClass
  │   ├── class GiveMeStructs
  │   ├── class GreetingAugmenter
@@ -89,6 +90,7 @@ assemblies
  │   ├── class ReturnsPrivateImplementationOfInterface
  │   ├── class RuntimeTypeChecking
  │   ├── class SingleInstanceTwoTypes
+ │   ├── class StableClass
  │   ├── class StaticContext
  │   ├── class Statics
  │   ├── class StripInternal
@@ -107,13 +109,17 @@ assemblies
  │   ├─┬ class CompositeOperation
  │   │ └── base: Operation
  │   ├── interface CalculatorProps
+ │   ├── interface DeprecatedStruct
  │   ├─┬ interface DerivedStruct
  │   │ └─┬ interfaces
  │   │   └── MyFirstStruct
  │   ├── interface EraseUndefinedHashValuesOptions
+ │   ├── interface ExperimentalStruct
  │   ├── interface ExtendsInternalInterface
  │   ├── interface Greetee
  │   ├── interface IAnotherPublicInterface
+ │   ├── interface IDeprecatedInterface
+ │   ├── interface IExperimentalInterface
  │   ├── interface IExtendsPrivateInterface
  │   ├─┬ interface IFriendlier
  │   │ └─┬ interfaces
@@ -149,6 +155,7 @@ assemblies
  │   ├── interface IPublicInterface2
  │   ├── interface IRandomNumberGenerator
  │   ├── interface IReturnsNumber
+ │   ├── interface IStableInterface
  │   ├─┬ interface ImplictBaseOfBase
  │   │ └─┬ interfaces
  │   │   └── BaseProps
@@ -157,9 +164,12 @@ assemblies
  │   ├── interface LoadBalancedFargateServiceProps
  │   ├── interface NullShouldBeTreatedAsUndefinedData
  │   ├── interface OptionalStruct
+ │   ├── interface StableStruct
  │   ├── interface UnionProperties
  │   ├── enum AllTypesEnum
- │   ├── enum StabilityTest
+ │   ├── enum DeprecatedEnum
+ │   ├── enum ExperimentalEnum
+ │   ├── enum StableEnum
  │   ├── enum StringEnum
  │   └── enum CompositionStringStyle
  ├─┬ @scope/jsii-calc-base
diff --git a/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
index 4f7d652a22..a434acf0ab 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.members.expected.txt
@@ -140,10 +140,10 @@ assemblies
  │   │   └── arg2 property
  │   ├─┬ class DeprecatedClass
  │   │ └─┬ members
- │   │   ├── <initializer>(argument) initializer
- │   │   ├── deprecatedMethod() method
- │   │   ├── deprecatedAttribute property
- │   │   └── deprecatedProtected property
+ │   │   ├── <initializer>(readonlyString,mutableNumber) initializer
+ │   │   ├── method() method
+ │   │   ├── readonlyProperty property
+ │   │   └── mutableProperty property
  │   ├─┬ class Base
  │   │ └─┬ members
  │   │   ├── <initializer>() initializer
@@ -181,6 +181,12 @@ assemblies
  │   │   ├── doesKeyExist(opts,key) method
  │   │   ├── prop1IsNull() method
  │   │   └── prop2IsUndefined() method
+ │   ├─┬ class ExperimentalClass
+ │   │ └─┬ members
+ │   │   ├── <initializer>(readonlyString,mutableNumber) initializer
+ │   │   ├── method() method
+ │   │   ├── readonlyProperty property
+ │   │   └── mutableProperty property
  │   ├─┬ class ExportedBaseClass
  │   │ └─┬ members
  │   │   ├── <initializer>(success) initializer
@@ -445,6 +451,12 @@ assemblies
  │   │   ├── <initializer>() initializer
  │   │   ├── interface1() method
  │   │   └── interface2() method
+ │   ├─┬ class StableClass
+ │   │ └─┬ members
+ │   │   ├── <initializer>(readonlyString,mutableNumber) initializer
+ │   │   ├── method() method
+ │   │   ├── readonlyProperty property
+ │   │   └── mutableProperty property
  │   ├─┬ class StaticContext
  │   │ └─┬ members
  │   │   ├── canAccessStaticContext() method
@@ -543,6 +555,9 @@ assemblies
  │   │ └─┬ members
  │   │   ├── initialValue property
  │   │   └── maximumValue property
+ │   ├─┬ interface DeprecatedStruct
+ │   │ └─┬ members
+ │   │   └── readonlyProperty property
  │   ├─┬ interface DerivedStruct
  │   │ └─┬ members
  │   │   ├── anotherRequired property
@@ -555,6 +570,9 @@ assemblies
  │   │ └─┬ members
  │   │   ├── option1 property
  │   │   └── option2 property
+ │   ├─┬ interface ExperimentalStruct
+ │   │ └─┬ members
+ │   │   └── readonlyProperty property
  │   ├─┬ interface ExtendsInternalInterface
  │   │ └─┬ members
  │   │   ├── boom property
@@ -565,6 +583,14 @@ assemblies
  │   ├─┬ interface IAnotherPublicInterface
  │   │ └─┬ members
  │   │   └── a property
+ │   ├─┬ interface IDeprecatedInterface
+ │   │ └─┬ members
+ │   │   ├── method() method
+ │   │   └── mutableProperty property
+ │   ├─┬ interface IExperimentalInterface
+ │   │ └─┬ members
+ │   │   ├── method() method
+ │   │   └── mutableProperty property
  │   ├─┬ interface IExtendsPrivateInterface
  │   │ └─┬ members
  │   │   ├── moreThings property
@@ -636,6 +662,10 @@ assemblies
  │   │ └─┬ members
  │   │   ├── obtainNumber() method
  │   │   └── numberProp property
+ │   ├─┬ interface IStableInterface
+ │   │ └─┬ members
+ │   │   ├── method() method
+ │   │   └── mutableProperty property
  │   ├─┬ interface ImplictBaseOfBase
  │   │ └─┬ members
  │   │   └── goo property
@@ -659,6 +689,9 @@ assemblies
  │   ├─┬ interface OptionalStruct
  │   │ └─┬ members
  │   │   └── field property
+ │   ├─┬ interface StableStruct
+ │   │ └─┬ members
+ │   │   └── readonlyProperty property
  │   ├─┬ interface UnionProperties
  │   │ └─┬ members
  │   │   ├── bar property
@@ -667,10 +700,15 @@ assemblies
  │   │ ├── MyEnumValue
  │   │ ├── YourEnumValue
  │   │ └── ThisIsGreat
- │   ├─┬ enum StabilityTest
- │   │ ├── DeprecatedMember
- │   │ ├── ExperimentalMember
- │   │ └── StableMember
+ │   ├─┬ enum DeprecatedEnum
+ │   │ ├── OptionA
+ │   │ └── OptionB
+ │   ├─┬ enum ExperimentalEnum
+ │   │ ├── OptionA
+ │   │ └── OptionB
+ │   ├─┬ enum StableEnum
+ │   │ ├── OptionA
+ │   │ └── OptionB
  │   ├─┬ enum StringEnum
  │   │ ├── A
  │   │ ├── B
diff --git a/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt b/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
index 5546e9ed4d..726ecf0266 100644
--- a/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
+++ b/packages/jsii-reflect/test/jsii-tree.test.types.expected.txt
@@ -29,6 +29,7 @@ assemblies
  │   ├── class DontComplainAboutVariadicAfterOptional
  │   ├── class DoubleTrouble
  │   ├── class EraseUndefinedHashValues
+ │   ├── class ExperimentalClass
  │   ├── class ExportedBaseClass
  │   ├── class GiveMeStructs
  │   ├── class GreetingAugmenter
@@ -66,6 +67,7 @@ assemblies
  │   ├── class ReturnsPrivateImplementationOfInterface
  │   ├── class RuntimeTypeChecking
  │   ├── class SingleInstanceTwoTypes
+ │   ├── class StableClass
  │   ├── class StaticContext
  │   ├── class Statics
  │   ├── class StripInternal
@@ -81,11 +83,15 @@ assemblies
  │   ├── class VoidCallback
  │   ├── class CompositeOperation
  │   ├── interface CalculatorProps
+ │   ├── interface DeprecatedStruct
  │   ├── interface DerivedStruct
  │   ├── interface EraseUndefinedHashValuesOptions
+ │   ├── interface ExperimentalStruct
  │   ├── interface ExtendsInternalInterface
  │   ├── interface Greetee
  │   ├── interface IAnotherPublicInterface
+ │   ├── interface IDeprecatedInterface
+ │   ├── interface IExperimentalInterface
  │   ├── interface IExtendsPrivateInterface
  │   ├── interface IFriendlier
  │   ├── interface IFriendlyRandomGenerator
@@ -108,15 +114,19 @@ assemblies
  │   ├── interface IPublicInterface2
  │   ├── interface IRandomNumberGenerator
  │   ├── interface IReturnsNumber
+ │   ├── interface IStableInterface
  │   ├── interface ImplictBaseOfBase
  │   ├── interface Hello
  │   ├── interface Hello
  │   ├── interface LoadBalancedFargateServiceProps
  │   ├── interface NullShouldBeTreatedAsUndefinedData
  │   ├── interface OptionalStruct
+ │   ├── interface StableStruct
  │   ├── interface UnionProperties
  │   ├── enum AllTypesEnum
- │   ├── enum StabilityTest
+ │   ├── enum DeprecatedEnum
+ │   ├── enum ExperimentalEnum
+ │   ├── enum StableEnum
  │   ├── enum StringEnum
  │   └── enum CompositionStringStyle
  ├─┬ @scope/jsii-calc-base

From d5c2b86320824f2909925900eef464fbcec04043 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Wed, 5 Jun 2019 15:51:53 +0200
Subject: [PATCH 9/9] Use different messages for different entities

---
 packages/jsii-calc/lib/stability.ts           | 28 ++++++++--------
 packages/jsii-calc/test/assembly.jsii         | 28 ++++++++--------
 .../.jsii                                     | 28 ++++++++--------
 .../CalculatorNamespace/DeprecatedClass.cs    | 14 ++++----
 .../CalculatorNamespace/DeprecatedEnum.cs     |  6 ++--
 .../CalculatorNamespace/DeprecatedStruct.cs   |  2 +-
 .../DeprecatedStructProxy.cs                  |  4 +--
 .../IDeprecatedInterfaceProxy.cs              |  6 ++--
 .../CalculatorNamespace/IDeprecatedStruct.cs  |  4 +--
 .../IIDeprecatedInterface.cs                  |  6 ++--
 .../tests/calculator/DeprecatedClass.java     | 14 ++++----
 .../jsii/tests/calculator/DeprecatedEnum.java |  6 ++--
 .../tests/calculator/DeprecatedStruct.java    |  8 ++---
 .../calculator/IDeprecatedInterface.java      | 14 ++++----
 .../python/src/jsii_calc/__init__.py          | 32 +++++++++----------
 15 files changed, 100 insertions(+), 100 deletions(-)

diff --git a/packages/jsii-calc/lib/stability.ts b/packages/jsii-calc/lib/stability.ts
index e0a3ccbe50..7fb132b0df 100644
--- a/packages/jsii-calc/lib/stability.ts
+++ b/packages/jsii-calc/lib/stability.ts
@@ -69,36 +69,36 @@ export enum StableEnum {
   OptionB
 }
 
-/** @deprecated for the show */
+/** @deprecated it just wraps a string */
 export interface DeprecatedStruct {
-  /** @deprecated for the show */
+  /** @deprecated well, yeah */
   readonly readonlyProperty: string;
 }
-/** @deprecated for the show */
+/** @deprecated useless interface */
 export interface IDeprecatedInterface {
-  /** @deprecated for the show */
+  /** @deprecated could be better */
   mutableProperty?: number;
-  /** @deprecated for the show */
+  /** @deprecated services no purpose */
   method(): void;
 }
-/** @deprecated for the show */
+/** @deprecated a pretty boring class */
 export class DeprecatedClass {
-  /** @deprecated for the show */
-  public readonly readonlyProperty: string = 'wazoo';
-  /** @deprecated for the show */
+  /** @deprecated this is not always "wazoo", be ready to be disappointed */
+  public readonly readonlyProperty: string;
+  /** @deprecated shouldn't have been mutable */
   public mutableProperty?: number;
-  /** @deprecated for the show */
+  /** @deprecated this constructor is "just" okay */
   constructor(readonlyString: string, mutableNumber?: number) {
     this.readonlyProperty = readonlyString;
     this.mutableProperty = mutableNumber;
   }
-  /** @deprecated for the show */
+  /** @deprecated it was a bad idea */
   public method(): void { return; }
 }
-/** @deprecated for the show */
+/** @deprecated your deprecated selection of bad options */
 export enum DeprecatedEnum {
-  /** @deprecated for the show */
+  /** @deprecated option A is not great */
   OptionA,
-  /** @deprecated for the show */
+  /** @deprecated option B is kinda bad, too */
   OptionB
 }
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
index a6b8a4027a..d89f670cd7 100644
--- a/packages/jsii-calc/test/assembly.jsii
+++ b/packages/jsii-calc/test/assembly.jsii
@@ -1892,13 +1892,13 @@
     "jsii-calc.DeprecatedClass": {
       "assembly": "jsii-calc",
       "docs": {
-        "deprecated": "for the show",
+        "deprecated": "a pretty boring class",
         "stability": "deprecated"
       },
       "fqn": "jsii-calc.DeprecatedClass",
       "initializer": {
         "docs": {
-          "deprecated": "for the show",
+          "deprecated": "this constructor is \"just\" okay",
           "stability": "deprecated"
         },
         "parameters": [
@@ -1925,7 +1925,7 @@
       "methods": [
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "it was a bad idea",
             "stability": "deprecated"
           },
           "locationInModule": {
@@ -1939,7 +1939,7 @@
       "properties": [
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "this is not always \"wazoo\", be ready to be disappointed",
             "stability": "deprecated"
           },
           "immutable": true,
@@ -1954,7 +1954,7 @@
         },
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "shouldn't have been mutable",
             "stability": "deprecated"
           },
           "locationInModule": {
@@ -1972,7 +1972,7 @@
     "jsii-calc.DeprecatedEnum": {
       "assembly": "jsii-calc",
       "docs": {
-        "deprecated": "for the show",
+        "deprecated": "your deprecated selection of bad options",
         "stability": "deprecated"
       },
       "fqn": "jsii-calc.DeprecatedEnum",
@@ -1984,14 +1984,14 @@
       "members": [
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "option A is not great",
             "stability": "deprecated"
           },
           "name": "OptionA"
         },
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "option B is kinda bad, too",
             "stability": "deprecated"
           },
           "name": "OptionB"
@@ -2003,7 +2003,7 @@
       "assembly": "jsii-calc",
       "datatype": true,
       "docs": {
-        "deprecated": "for the show",
+        "deprecated": "it just wraps a string",
         "stability": "deprecated"
       },
       "fqn": "jsii-calc.DeprecatedStruct",
@@ -2017,7 +2017,7 @@
         {
           "abstract": true,
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "well, yeah",
             "stability": "deprecated"
           },
           "immutable": true,
@@ -2929,7 +2929,7 @@
     "jsii-calc.IDeprecatedInterface": {
       "assembly": "jsii-calc",
       "docs": {
-        "deprecated": "for the show",
+        "deprecated": "useless interface",
         "stability": "deprecated"
       },
       "fqn": "jsii-calc.IDeprecatedInterface",
@@ -2942,7 +2942,7 @@
         {
           "abstract": true,
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "services no purpose",
             "stability": "deprecated"
           },
           "locationInModule": {
@@ -2957,7 +2957,7 @@
         {
           "abstract": true,
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "could be better",
             "stability": "deprecated"
           },
           "locationInModule": {
@@ -7354,5 +7354,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "7WPX4JJX9K3lSIehbMBcjNATyKWXOa3SXA/ct2gisGc="
+  "fingerprint": "aNWCih3NfgXU4mll5c+zKXj3ekSyaT9S+67MAugCfNo="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
index a6b8a4027a..d89f670cd7 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
@@ -1892,13 +1892,13 @@
     "jsii-calc.DeprecatedClass": {
       "assembly": "jsii-calc",
       "docs": {
-        "deprecated": "for the show",
+        "deprecated": "a pretty boring class",
         "stability": "deprecated"
       },
       "fqn": "jsii-calc.DeprecatedClass",
       "initializer": {
         "docs": {
-          "deprecated": "for the show",
+          "deprecated": "this constructor is \"just\" okay",
           "stability": "deprecated"
         },
         "parameters": [
@@ -1925,7 +1925,7 @@
       "methods": [
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "it was a bad idea",
             "stability": "deprecated"
           },
           "locationInModule": {
@@ -1939,7 +1939,7 @@
       "properties": [
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "this is not always \"wazoo\", be ready to be disappointed",
             "stability": "deprecated"
           },
           "immutable": true,
@@ -1954,7 +1954,7 @@
         },
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "shouldn't have been mutable",
             "stability": "deprecated"
           },
           "locationInModule": {
@@ -1972,7 +1972,7 @@
     "jsii-calc.DeprecatedEnum": {
       "assembly": "jsii-calc",
       "docs": {
-        "deprecated": "for the show",
+        "deprecated": "your deprecated selection of bad options",
         "stability": "deprecated"
       },
       "fqn": "jsii-calc.DeprecatedEnum",
@@ -1984,14 +1984,14 @@
       "members": [
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "option A is not great",
             "stability": "deprecated"
           },
           "name": "OptionA"
         },
         {
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "option B is kinda bad, too",
             "stability": "deprecated"
           },
           "name": "OptionB"
@@ -2003,7 +2003,7 @@
       "assembly": "jsii-calc",
       "datatype": true,
       "docs": {
-        "deprecated": "for the show",
+        "deprecated": "it just wraps a string",
         "stability": "deprecated"
       },
       "fqn": "jsii-calc.DeprecatedStruct",
@@ -2017,7 +2017,7 @@
         {
           "abstract": true,
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "well, yeah",
             "stability": "deprecated"
           },
           "immutable": true,
@@ -2929,7 +2929,7 @@
     "jsii-calc.IDeprecatedInterface": {
       "assembly": "jsii-calc",
       "docs": {
-        "deprecated": "for the show",
+        "deprecated": "useless interface",
         "stability": "deprecated"
       },
       "fqn": "jsii-calc.IDeprecatedInterface",
@@ -2942,7 +2942,7 @@
         {
           "abstract": true,
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "services no purpose",
             "stability": "deprecated"
           },
           "locationInModule": {
@@ -2957,7 +2957,7 @@
         {
           "abstract": true,
           "docs": {
-            "deprecated": "for the show",
+            "deprecated": "could be better",
             "stability": "deprecated"
           },
           "locationInModule": {
@@ -7354,5 +7354,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "7WPX4JJX9K3lSIehbMBcjNATyKWXOa3SXA/ct2gisGc="
+  "fingerprint": "aNWCih3NfgXU4mll5c+zKXj3ekSyaT9S+67MAugCfNo="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
index 77234ee5e2..b4709f9158 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedClass.cs
@@ -4,28 +4,28 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
 {
     /// <remarks>stability: Deprecated</remarks>
     [JsiiClass(nativeType: typeof(DeprecatedClass), fullyQualifiedName: "jsii-calc.DeprecatedClass", parametersJson: "[{\"name\":\"readonlyString\",\"type\":{\"primitive\":\"string\"}},{\"name\":\"mutableNumber\",\"type\":{\"primitive\":\"number\"},\"optional\":true}]")]
-    [System.Obsolete("for the show")]
+    [System.Obsolete("a pretty boring class")]
     public class DeprecatedClass : DeputyBase
     {
         /// <remarks>stability: Deprecated</remarks>
-        [System.Obsolete("for the show")]
+        [System.Obsolete("this constructor is \"just\" okay")]
         public DeprecatedClass(string readonlyString, double? mutableNumber): base(new DeputyProps(new object[]{readonlyString, mutableNumber}))
         {
         }
 
-        [System.Obsolete("for the show")]
+        [System.Obsolete("this constructor is \"just\" okay")]
         protected DeprecatedClass(ByRefValue reference): base(reference)
         {
         }
 
-        [System.Obsolete("for the show")]
+        [System.Obsolete("this constructor is \"just\" okay")]
         protected DeprecatedClass(DeputyProps props): base(props)
         {
         }
 
         /// <remarks>stability: Deprecated</remarks>
         [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("this is not always \"wazoo\", be ready to be disappointed")]
         public virtual string ReadonlyProperty
         {
             get => GetInstanceProperty<string>();
@@ -33,7 +33,7 @@ public virtual string ReadonlyProperty
 
         /// <remarks>stability: Deprecated</remarks>
         [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("shouldn't have been mutable")]
         public virtual double? MutableProperty
         {
             get => GetInstanceProperty<double? >();
@@ -42,7 +42,7 @@ public virtual double? MutableProperty
 
         /// <remarks>stability: Deprecated</remarks>
         [JsiiMethod(name: "method")]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("it was a bad idea")]
         public virtual void Method()
         {
             InvokeInstanceVoidMethod(new object[]{});
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedEnum.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedEnum.cs
index 48cf148fa5..f2a4472519 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedEnum.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedEnum.cs
@@ -4,16 +4,16 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
 {
     /// <remarks>stability: Deprecated</remarks>
     [JsiiEnum(nativeType: typeof(DeprecatedEnum), fullyQualifiedName: "jsii-calc.DeprecatedEnum")]
-    [System.Obsolete("for the show")]
+    [System.Obsolete("your deprecated selection of bad options")]
     public enum DeprecatedEnum
     {
         /// <remarks>stability: Deprecated</remarks>
         [JsiiEnumMember(name: "OptionA")]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("option A is not great")]
         OptionA,
         /// <remarks>stability: Deprecated</remarks>
         [JsiiEnumMember(name: "OptionB")]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("option B is kinda bad, too")]
         OptionB
     }
 }
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStruct.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStruct.cs
index 5f8f8545af..50f74cb69a 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStruct.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStruct.cs
@@ -8,7 +8,7 @@ public class DeprecatedStruct : IDeprecatedStruct
     {
         /// <remarks>stability: Deprecated</remarks>
         [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}", isOverride: true)]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("well, yeah")]
         public string ReadonlyProperty
         {
             get;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStructProxy.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStructProxy.cs
index aabfe4dbc1..e741342829 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStructProxy.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/DeprecatedStructProxy.cs
@@ -4,7 +4,7 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
 {
     /// <remarks>stability: Deprecated</remarks>
     [JsiiTypeProxy(nativeType: typeof(IDeprecatedStruct), fullyQualifiedName: "jsii-calc.DeprecatedStruct")]
-    [System.Obsolete("for the show")]
+    [System.Obsolete("it just wraps a string")]
     internal sealed class DeprecatedStructProxy : DeputyBase, IDeprecatedStruct
     {
         private DeprecatedStructProxy(ByRefValue reference): base(reference)
@@ -13,7 +13,7 @@ private DeprecatedStructProxy(ByRefValue reference): base(reference)
 
         /// <remarks>stability: Deprecated</remarks>
         [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("well, yeah")]
         public string ReadonlyProperty
         {
             get => GetInstanceProperty<string>();
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedInterfaceProxy.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedInterfaceProxy.cs
index 710e3cf733..95dbe136b5 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedInterfaceProxy.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedInterfaceProxy.cs
@@ -4,7 +4,7 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
 {
     /// <remarks>stability: Deprecated</remarks>
     [JsiiTypeProxy(nativeType: typeof(IIDeprecatedInterface), fullyQualifiedName: "jsii-calc.IDeprecatedInterface")]
-    [System.Obsolete("for the show")]
+    [System.Obsolete("useless interface")]
     internal sealed class IDeprecatedInterfaceProxy : DeputyBase, IIDeprecatedInterface
     {
         private IDeprecatedInterfaceProxy(ByRefValue reference): base(reference)
@@ -13,7 +13,7 @@ private IDeprecatedInterfaceProxy(ByRefValue reference): base(reference)
 
         /// <remarks>stability: Deprecated</remarks>
         [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("could be better")]
         public double? MutableProperty
         {
             get => GetInstanceProperty<double? >();
@@ -22,7 +22,7 @@ public double? MutableProperty
 
         /// <remarks>stability: Deprecated</remarks>
         [JsiiMethod(name: "method")]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("services no purpose")]
         public void Method()
         {
             InvokeInstanceVoidMethod(new object[]{});
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedStruct.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedStruct.cs
index c822069170..313d2d6755 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedStruct.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IDeprecatedStruct.cs
@@ -4,12 +4,12 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
 {
     /// <remarks>stability: Deprecated</remarks>
     [JsiiInterface(nativeType: typeof(IDeprecatedStruct), fullyQualifiedName: "jsii-calc.DeprecatedStruct")]
-    [System.Obsolete("for the show")]
+    [System.Obsolete("it just wraps a string")]
     public interface IDeprecatedStruct
     {
         /// <remarks>stability: Deprecated</remarks>
         [JsiiProperty(name: "readonlyProperty", typeJson: "{\"primitive\":\"string\"}")]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("well, yeah")]
         string ReadonlyProperty
         {
             get;
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIDeprecatedInterface.cs b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIDeprecatedInterface.cs
index 2ee06030b7..83fe6ecf8e 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIDeprecatedInterface.cs
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/Amazon/JSII/Tests/CalculatorNamespace/IIDeprecatedInterface.cs
@@ -4,12 +4,12 @@ namespace Amazon.JSII.Tests.CalculatorNamespace
 {
     /// <remarks>stability: Deprecated</remarks>
     [JsiiInterface(nativeType: typeof(IIDeprecatedInterface), fullyQualifiedName: "jsii-calc.IDeprecatedInterface")]
-    [System.Obsolete("for the show")]
+    [System.Obsolete("useless interface")]
     public interface IIDeprecatedInterface
     {
         /// <remarks>stability: Deprecated</remarks>
         [JsiiProperty(name: "mutableProperty", typeJson: "{\"primitive\":\"number\"}", isOptional: true)]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("could be better")]
         double? MutableProperty
         {
             get;
@@ -18,7 +18,7 @@ public interface IIDeprecatedInterface
 
         /// <remarks>stability: Deprecated</remarks>
         [JsiiMethod(name: "method")]
-        [System.Obsolete("for the show")]
+        [System.Obsolete("services no purpose")]
         void Method();
     }
 }
\ No newline at end of file
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
index 68eee6b5a7..c51dca701b 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedClass.java
@@ -1,7 +1,7 @@
 package software.amazon.jsii.tests.calculator;
 
 /**
- * @deprecated for the show
+ * @deprecated a pretty boring class
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
 @Deprecated
@@ -12,7 +12,7 @@ protected DeprecatedClass(final software.amazon.jsii.JsiiObject.InitializationMo
         super(mode);
     }
     /**
-     * @deprecated for the show
+     * @deprecated this constructor is "just" okay
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@@ -21,7 +21,7 @@ public DeprecatedClass(final java.lang.String readonlyString, @javax.annotation.
         software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(readonlyString, "readonlyString is required"), mutableNumber });
     }
     /**
-     * @deprecated for the show
+     * @deprecated this constructor is "just" okay
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@@ -31,7 +31,7 @@ public DeprecatedClass(final java.lang.String readonlyString) {
     }
 
     /**
-     * @deprecated for the show
+     * @deprecated it was a bad idea
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@@ -40,7 +40,7 @@ public void method() {
     }
 
     /**
-     * @deprecated for the show
+     * @deprecated this is not always "wazoo", be ready to be disappointed
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@@ -49,7 +49,7 @@ public java.lang.String getReadonlyProperty() {
     }
 
     /**
-     * @deprecated for the show
+     * @deprecated shouldn't have been mutable
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@@ -59,7 +59,7 @@ public java.lang.Number getMutableProperty() {
     }
 
     /**
-     * @deprecated for the show
+     * @deprecated shouldn't have been mutable
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedEnum.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedEnum.java
index 6bd86cbbab..2200438388 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedEnum.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedEnum.java
@@ -1,7 +1,7 @@
 package software.amazon.jsii.tests.calculator;
 
 /**
- * @deprecated for the show
+ * @deprecated your deprecated selection of bad options
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
 @Deprecated
@@ -9,13 +9,13 @@
 @software.amazon.jsii.Jsii(module = software.amazon.jsii.tests.calculator.$Module.class, fqn = "jsii-calc.DeprecatedEnum")
 public enum DeprecatedEnum {
     /**
-     * @deprecated for the show
+     * @deprecated option A is not great
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     OptionA,
     /**
-     * @deprecated for the show
+     * @deprecated option B is kinda bad, too
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java
index e55dfb90d3..2a5a1876d6 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java
@@ -1,14 +1,14 @@
 package software.amazon.jsii.tests.calculator;
 
 /**
- * @deprecated for the show
+ * @deprecated it just wraps a string
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
 @Deprecated
 @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
 public interface DeprecatedStruct extends software.amazon.jsii.JsiiSerializable {
     /**
-     * @deprecated for the show
+     * @deprecated well, yeah
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@@ -35,7 +35,7 @@ final class Builder {
          * Sets the value of ReadonlyProperty
          * @param value the value to be set
          * @return {@code this}
-         * @deprecated for the show
+         * @deprecated well, yeah
          */
         @Deprecated
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@@ -80,7 +80,7 @@ final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements
         }
 
         /**
-         * @deprecated for the show
+         * @deprecated well, yeah
          */
         @Override
         @Deprecated
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IDeprecatedInterface.java b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IDeprecatedInterface.java
index 7ad15eedf7..0ce4d4b6bc 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IDeprecatedInterface.java
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/IDeprecatedInterface.java
@@ -1,24 +1,24 @@
 package software.amazon.jsii.tests.calculator;
 
 /**
- * @deprecated for the show
+ * @deprecated useless interface
  */
 @javax.annotation.Generated(value = "jsii-pacmak")
 @Deprecated
 @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
 public interface IDeprecatedInterface extends software.amazon.jsii.JsiiSerializable {
     /**
-     * @deprecated for the show
+     * @deprecated could be better
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     java.lang.Number getMutableProperty();
     /**
-     * @deprecated for the show
+     * @deprecated could be better
      */
     void setMutableProperty(final java.lang.Number value);
     /**
-     * @deprecated for the show
+     * @deprecated services no purpose
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
@@ -33,7 +33,7 @@ final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements
         }
 
         /**
-         * @deprecated for the show
+         * @deprecated could be better
          */
         @Override
         @Deprecated
@@ -44,7 +44,7 @@ public java.lang.Number getMutableProperty() {
         }
 
         /**
-         * @deprecated for the show
+         * @deprecated could be better
          */
         @Override
         @Deprecated
@@ -54,7 +54,7 @@ public void setMutableProperty(@javax.annotation.Nullable final java.lang.Number
         }
 
         /**
-         * @deprecated for the show
+         * @deprecated services no purpose
          */
         @Deprecated
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py b/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
index 15f8b398a2..877e66397c 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__init__.py
@@ -552,7 +552,7 @@ def arg2(self) -> typing.Optional[str]:
 class DeprecatedClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.DeprecatedClass"):
     """
     Deprecated:
-        for the show
+        a pretty boring class
 
     Stability:
         deprecated
@@ -564,7 +564,7 @@ def __init__(self, readonly_string: str, mutable_number: typing.Optional[jsii.Nu
             mutableNumber: -
 
         Deprecated:
-            for the show
+            this constructor is "just" okay
 
         Stability:
             deprecated
@@ -575,7 +575,7 @@ def __init__(self, readonly_string: str, mutable_number: typing.Optional[jsii.Nu
     def method(self) -> None:
         """
         Deprecated:
-            for the show
+            it was a bad idea
 
         Stability:
             deprecated
@@ -587,7 +587,7 @@ def method(self) -> None:
     def readonly_property(self) -> str:
         """
         Deprecated:
-            for the show
+            this is not always "wazoo", be ready to be disappointed
 
         Stability:
             deprecated
@@ -599,7 +599,7 @@ def readonly_property(self) -> str:
     def mutable_property(self) -> typing.Optional[jsii.Number]:
         """
         Deprecated:
-            for the show
+            shouldn't have been mutable
 
         Stability:
             deprecated
@@ -615,7 +615,7 @@ def mutable_property(self, value: typing.Optional[jsii.Number]):
 class DeprecatedEnum(enum.Enum):
     """
     Deprecated:
-        for the show
+        your deprecated selection of bad options
 
     Stability:
         deprecated
@@ -623,7 +623,7 @@ class DeprecatedEnum(enum.Enum):
     OptionA = "OptionA"
     """
     Deprecated:
-        for the show
+        option A is not great
 
     Stability:
         deprecated
@@ -631,7 +631,7 @@ class DeprecatedEnum(enum.Enum):
     OptionB = "OptionB"
     """
     Deprecated:
-        for the show
+        option B is kinda bad, too
 
     Stability:
         deprecated
@@ -641,7 +641,7 @@ class DeprecatedEnum(enum.Enum):
 class DeprecatedStruct(jsii.compat.TypedDict):
     """
     Deprecated:
-        for the show
+        it just wraps a string
 
     Stability:
         deprecated
@@ -649,7 +649,7 @@ class DeprecatedStruct(jsii.compat.TypedDict):
     readonlyProperty: str
     """
     Deprecated:
-        for the show
+        well, yeah
 
     Stability:
         deprecated
@@ -1068,7 +1068,7 @@ def a(self, value: str):
 class IDeprecatedInterface(jsii.compat.Protocol):
     """
     Deprecated:
-        for the show
+        useless interface
 
     Stability:
         deprecated
@@ -1082,7 +1082,7 @@ def __jsii_proxy_class__():
     def mutable_property(self) -> typing.Optional[jsii.Number]:
         """
         Deprecated:
-            for the show
+            could be better
 
         Stability:
             deprecated
@@ -1097,7 +1097,7 @@ def mutable_property(self, value: typing.Optional[jsii.Number]):
     def method(self) -> None:
         """
         Deprecated:
-            for the show
+            services no purpose
 
         Stability:
             deprecated
@@ -1108,7 +1108,7 @@ def method(self) -> None:
 class _IDeprecatedInterfaceProxy():
     """
     Deprecated:
-        for the show
+        useless interface
 
     Stability:
         deprecated
@@ -1119,7 +1119,7 @@ class _IDeprecatedInterfaceProxy():
     def mutable_property(self) -> typing.Optional[jsii.Number]:
         """
         Deprecated:
-            for the show
+            could be better
 
         Stability:
             deprecated
@@ -1134,7 +1134,7 @@ def mutable_property(self, value: typing.Optional[jsii.Number]):
     def method(self) -> None:
         """
         Deprecated:
-            for the show
+            services no purpose
 
         Stability:
             deprecated