feat(jsii): reflect stabilities in doc comment summaries (#1951)

In order to make the stability of certain API elements more clear, note any non-standard API stabilities in the APIs summary docstring. This makes it clearly visible in the IDEs autocomplete. IMPLEMENTATION NOTES We put the onus of rendering of the `(experimental)/(deprecated)` prefixes on the code generators for every language. We played with the idea of sticking it directly into the manifest but then the API reference would also have had it, and the API reference already has color coding and graphical symbols to indicate these statuses. To modify the `.js/.d.ts` generation: * Reversed the order of `program.emit()` and `assembler.emit()`. `assembler.emit()` now comes first, so that we know the correct stability before we start emitting code. * For every node we encounter, we regenerate the doc comment block to include stability in the summary line if appropriate. We remember the desired doc comment block for later. * The annotation is being done by TypeScript transforms. The original comments are stripped out of the SourceFile (in-memory) and replaced with synthetic comments containing the generated doc comments.
aws · Sep 1, 2020 · ce8c0c4 · ce8c0c4
1 parent 7e2512f
commit ce8c0c4
Show file tree

Hide file tree

Showing 18 changed files with 815 additions and 283 deletions.
diff --git a/packages/@scope/jsii-calc-base-of-base/lib/index.ts b/packages/@scope/jsii-calc-base-of-base/lib/index.ts
@@ -6,6 +6,10 @@ export interface VeryBaseProps {
     readonly foo: Very;
 }
 
+/**
+ * Something here
+ * @experimental
+ */
 export class Very {
     public hey() {
         return 42;

diff --git a/packages/@scope/jsii-calc-base-of-base/test/assembly.jsii b/packages/@scope/jsii-calc-base-of-base/test/assembly.jsii
@@ -68,13 +68,13 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/index.ts",
-        "line": 15
+        "line": 19
       },
       "methods": [
         {
           "locationInModule": {
             "filename": "lib/index.ts",
-            "line": 18
+            "line": 22
           },
           "name": "consume",
           "parameters": [
@@ -94,18 +94,25 @@
     },
     "@scope/jsii-calc-base-of-base.Very": {
       "assembly": "@scope/jsii-calc-base-of-base",
+      "docs": {
+        "stability": "experimental",
+        "summary": "Something here."
+      },
       "fqn": "@scope/jsii-calc-base-of-base.Very",
       "initializer": {},
       "kind": "class",
       "locationInModule": {
         "filename": "lib/index.ts",
-        "line": 9
+        "line": 13
       },
       "methods": [
         {
+          "docs": {
+            "stability": "experimental"
+          },
           "locationInModule": {
             "filename": "lib/index.ts",
-            "line": 10
+            "line": 14
           },
           "name": "hey",
           "returns": {
@@ -144,5 +151,5 @@
     }
   },
   "version": "0.0.0",
-  "fingerprint": "jza6cUA8sUzeQheSillLX/NlWEInEXLHp27JTZNQqUE="
+  "fingerprint": "XzppfL+BknRpBHYygvGjf8OOXrTyNAx6cllN3vONLoU="
 }
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
@@ -169,7 +169,7 @@
     "@scope/jsii-calc-lib.submodule": {
       "locationInModule": {
         "filename": "../@scope/jsii-calc-lib/build/index.d.ts",
-        "line": 94
+        "line": 157
       }
     },
     "jsii-calc.DerivedClassHasNoProperties": {
@@ -586,7 +586,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "String representation of the value."
+            "summary": "(deprecated) String representation of the value."
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
@@ -606,7 +606,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "The value."
+            "summary": "(deprecated) The value."
           },
           "immutable": true,
           "locationInModule": {
@@ -1587,7 +1587,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "Say hello!"
+            "summary": "(deprecated) Say hello!"
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
@@ -4255,7 +4255,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "Say hello!"
+            "summary": "(deprecated) Say hello!"
           },
           "locationInModule": {
             "filename": "lib/compliance.ts",
@@ -8430,7 +8430,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "String representation of the value."
+            "summary": "(deprecated) String representation of the value."
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
@@ -8450,7 +8450,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "The value."
+            "summary": "(deprecated) The value."
           },
           "immutable": true,
           "locationInModule": {
@@ -8536,7 +8536,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "Say hello!"
+            "summary": "(deprecated) Say hello!"
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
@@ -8553,7 +8553,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "String representation of the value."
+            "summary": "(deprecated) String representation of the value."
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
@@ -8573,7 +8573,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "The value."
+            "summary": "(deprecated) The value."
           },
           "immutable": true,
           "locationInModule": {
@@ -13308,7 +13308,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "String representation of the value."
+            "summary": "(deprecated) String representation of the value."
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
@@ -13346,7 +13346,7 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "The value."
+            "summary": "(deprecated) The value."
           },
           "immutable": true,
           "locationInModule": {
@@ -13968,5 +13968,5 @@
     }
   },
   "version": "0.0.0",
-  "fingerprint": "D7hjrHXe6ctuIKevB3YN+761WFtPs6LykV2nsXQRHTM="
+  "fingerprint": "Rp4Cw4yqvAfwyiUl5zmEHzvLlWXhUMNMwzWQYkG/1io="
 }
diff --git a/packages/jsii-pacmak/lib/targets/_utils.ts b/packages/jsii-pacmak/lib/targets/_utils.ts
@@ -0,0 +1,15 @@
+import * as spec from '@jsii/spec';
+
+export function stabilityPrefixFor(element: spec.Documentable): string {
+  if (element.docs?.stability === spec.Stability.Experimental) {
+    return '(experimental) ';
+  }
+  if (element.docs?.stability === spec.Stability.Deprecated) {
+    return '(deprecated) ';
+  }
+  return '';
+}
+
+export function renderSummary(docs?: spec.Docs): string {
+  return docs?.summary ? stabilityPrefixFor({ docs }) + docs.summary : '';
+}
diff --git a/packages/jsii-pacmak/lib/targets/dotnet/dotnetdocgenerator.ts b/packages/jsii-pacmak/lib/targets/dotnet/dotnetdocgenerator.ts
@@ -12,6 +12,7 @@ import {
   INCOMPLETE_DISCLAIMER_COMPILING,
   INCOMPLETE_DISCLAIMER_NONCOMPILING,
 } from '..';
+import { renderSummary } from '../_utils';
 
 /**
  * Generates the Jsii attributes and calls for the .NET runtime
@@ -40,7 +41,7 @@ export class DotNetDocGenerator {
     const docs = obj.docs;
 
     // The docs may be undefined at the method level but not the parameters level
-    this.emitXmlDoc('summary', docs?.summary || '');
+    this.emitXmlDoc('summary', renderSummary(obj.docs));
 
     // Handling parameters only if the obj is a method
     const objMethod = obj as spec.Method;

diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
@@ -28,6 +28,7 @@ import {
   INCOMPLETE_DISCLAIMER_COMPILING,
   INCOMPLETE_DISCLAIMER_NONCOMPILING,
 } from '.';
+import { stabilityPrefixFor, renderSummary } from './_utils';
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires,@typescript-eslint/no-require-imports
 const spdxLicenseList = require('spdx-license-list');
@@ -1545,7 +1546,8 @@ class JavaGenerator extends Generator {
 
     this.code.line();
     this.code.line('/**');
-    this.code.line(` * A fluent builder for {@link ${builtType}}.`);
+    // eslint-disable-next-line prettier/prettier
+    this.code.line(` * ${stabilityPrefixFor(cls.initializer)}A fluent builder for {@link ${builtType}}.`);
     this.code.line(' */');
     this.emitStabilityAnnotations(cls.initializer);
     this.code.openBlock(
@@ -2123,7 +2125,7 @@ class JavaGenerator extends Generator {
     const paras = [];
 
     if (docs.summary) {
-      paras.push(docs.summary);
+      paras.push(renderSummary(docs));
     } else if (defaultText) {
       paras.push(defaultText);
     }
@@ -2149,10 +2151,6 @@ class JavaGenerator extends Generator {
       );
     }
 
-    if (docs.stability === spec.Stability.Experimental) {
-      paras.push('EXPERIMENTAL');
-    }
-
     const tagLines = [];
 
     if (docs.returns) {

diff --git a/packages/jsii-pacmak/lib/targets/python.ts b/packages/jsii-pacmak/lib/targets/python.ts
@@ -27,6 +27,7 @@ import {
   toPackageName,
 } from './python/type-name';
 import { die, toPythonIdentifier } from './python/util';
+import { renderSummary } from './_utils';
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires,@typescript-eslint/no-require-imports
 const spdxLicenseList = require('spdx-license-list');
@@ -1976,7 +1977,7 @@ class PythonGenerator extends Generator {
     const lines = new Array<string>();
 
     if (docs.summary) {
-      lines.push(md2rst(docs.summary));
+      lines.push(md2rst(renderSummary(docs)));
       brk();
     } else {
       lines.push('');
@@ -2508,7 +2509,7 @@ function onelineDescription(docs: spec.Docs | undefined) {
 
   const parts = [];
   if (docs.summary) {
-    parts.push(md2rst(docs.summary));
+    parts.push(md2rst(renderSummary(docs)));
   }
   if (docs.remarks) {
     parts.push(md2rst(docs.remarks));