feat(jsii-diff): standardize doc comments, add API compatibility tool (#415)

Add parsing semantics for various common capabilities to doc comments
(summary, remarks, stability and others).

Add a tool uses stability annotations in the doc comments to check
whether two JSII assemblies are API-compatible.

Author: rix0rrr

package-lock.json

@@ -68,7 +68,7 @@
       "abstract": true,
       "assembly": "@scope/jsii-calc-base",
       "docs": {
-        "comment": "A base class."
+        "summary": "A base class."
       },
       "fqn": "@scope/jsii-calc-base.Base",
       "initializer": {
@@ -78,7 +78,7 @@
       "methods": [
         {
           "docs": {
-            "return": "the name of the class (to verify native type names are created for derived classes)."
+            "returns": "the name of the class (to verify native type names are created for derived classes)."
           },
           "name": "typeName",
           "returns": {
@@ -112,5 +112,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "rxvvJXFGzGZKodg4kjh0+uD9J3GU64sbBwcOkTFU9l8="
+  "fingerprint": "lIcHicx5rBBxyy5vOvOqvbBGjk//8lFLX6oVx2xh5Fc="
 }

packages/codemaker/package-lock.json

@@ -91,7 +91,7 @@ export interface StructWithOnlyOptionals {
 }
 
 /**
- * Check that enums from @scoped packages can be references.
+ * Check that enums from \@scoped packages can be references.
  * See awslabs/jsii#138
  */
 export enum EnumFromScopedModule {

packages/jsii-build-tools/package-lock.json

@@ -93,7 +93,7 @@
     "@scope/jsii-calc-lib.EnumFromScopedModule": {
       "assembly": "@scope/jsii-calc-lib",
       "docs": {
-        "comment": "Check that enums from @scoped packages can be references.\nSee awslabs/jsii#138"
+        "summary": "Check that enums from \\@scoped packages can be references. See awslabs/jsii#138."
       },
       "fqn": "@scope/jsii-calc-lib.EnumFromScopedModule",
       "kind": "enum",
@@ -110,7 +110,7 @@
     "@scope/jsii-calc-lib.IDoublable": {
       "assembly": "@scope/jsii-calc-lib",
       "docs": {
-        "comment": "The general contract for a concrete number."
+        "summary": "The general contract for a concrete number."
       },
       "fqn": "@scope/jsii-calc-lib.IDoublable",
       "kind": "interface",
@@ -129,15 +129,16 @@
     "@scope/jsii-calc-lib.IFriendly": {
       "assembly": "@scope/jsii-calc-lib",
       "docs": {
-        "comment": "Applies to classes that are considered friendly. These classes can be greeted with\na \"hello\" or \"goodbye\" blessing and they will respond back in a fun and friendly manner."
+        "remarks": "These classes can be greeted with\na \"hello\" or \"goodbye\" blessing and they will respond back in a fun and friendly manner.",
+        "summary": "Applies to classes that are considered friendly."
       },
       "fqn": "@scope/jsii-calc-lib.IFriendly",
       "kind": "interface",
       "methods": [
         {
           "abstract": true,
           "docs": {
-            "comment": "Say hello!"
+            "summary": "Say hello!"
           },
           "name": "hello",
           "returns": {
@@ -151,7 +152,7 @@
       "assembly": "@scope/jsii-calc-lib",
       "datatype": true,
       "docs": {
-        "comment": "This is the first struct we have created in jsii"
+        "summary": "This is the first struct we have created in jsii."
       },
       "fqn": "@scope/jsii-calc-lib.MyFirstStruct",
       "kind": "interface",
@@ -160,7 +161,7 @@
         {
           "abstract": true,
           "docs": {
-            "comment": "An awesome number value"
+            "summary": "An awesome number value."
           },
           "immutable": true,
           "name": "anumber",
@@ -171,7 +172,7 @@
         {
           "abstract": true,
           "docs": {
-            "comment": "A string value"
+            "summary": "A string value."
           },
           "immutable": true,
           "name": "astring",
@@ -201,18 +202,18 @@
         "fqn": "@scope/jsii-calc-lib.Value"
       },
       "docs": {
-        "comment": "Represents a concrete number."
+        "summary": "Represents a concrete number."
       },
       "fqn": "@scope/jsii-calc-lib.Number",
       "initializer": {
         "docs": {
-          "comment": "Creates a Number object."
+          "summary": "Creates a Number object."
         },
         "initializer": true,
         "parameters": [
           {
             "docs": {
-              "comment": "The number."
+              "summary": "The number."
             },
             "name": "value",
             "type": {
@@ -231,7 +232,7 @@
       "properties": [
         {
           "docs": {
-            "comment": "The number multiplied by 2."
+            "summary": "The number multiplied by 2."
           },
           "immutable": true,
           "name": "doubleValue",
@@ -244,7 +245,7 @@
         },
         {
           "docs": {
-            "comment": "The number."
+            "summary": "The number."
           },
           "immutable": true,
           "name": "value",
@@ -264,7 +265,7 @@
         "fqn": "@scope/jsii-calc-lib.Value"
       },
       "docs": {
-        "comment": "Represents an operation on values."
+        "summary": "Represents an operation on values."
       },
       "fqn": "@scope/jsii-calc-lib.Operation",
       "initializer": {
@@ -275,7 +276,7 @@
         {
           "abstract": true,
           "docs": {
-            "comment": "String representation of the value."
+            "summary": "String representation of the value."
           },
           "name": "toString",
           "overrides": {
@@ -292,7 +293,7 @@
       "assembly": "@scope/jsii-calc-lib",
       "datatype": true,
       "docs": {
-        "comment": "This is a struct with only optional properties."
+        "summary": "This is a struct with only optional properties."
       },
       "fqn": "@scope/jsii-calc-lib.StructWithOnlyOptionals",
       "kind": "interface",
@@ -301,7 +302,7 @@
         {
           "abstract": true,
           "docs": {
-            "comment": "The first optional!"
+            "summary": "The first optional!"
           },
           "immutable": true,
           "name": "optional1",
@@ -337,7 +338,7 @@
         "fqn": "@scope/jsii-calc-base.Base"
       },
       "docs": {
-        "comment": "Abstract class which represents a numeric value."
+        "summary": "Abstract class which represents a numeric value."
       },
       "fqn": "@scope/jsii-calc-lib.Value",
       "initializer": {
@@ -347,7 +348,7 @@
       "methods": [
         {
           "docs": {
-            "comment": "String representation of the value."
+            "summary": "String representation of the value."
           },
           "name": "toString",
           "returns": {
@@ -360,7 +361,7 @@
         {
           "abstract": true,
           "docs": {
-            "comment": "The value."
+            "summary": "The value."
           },
           "immutable": true,
           "name": "value",
@@ -372,5 +373,5 @@
     }
   },
   "version": "0.8.2",
-  "fingerprint": "ydArnwt9qdOM1IiBaOFzS2A7t9/+na0q+OibmkwQrEg="
+  "fingerprint": "SDQQzBvYRO3SXfWWgpKwLDSy3EgMqP/e6rd75kblKA0="
 }

packages/jsii-calc-base/test/assembly.jsii

@@ -641,14 +641,14 @@ export class VariadicMethod {
     private readonly prefix: number[];
 
     /**
-     * @param prefix a prefix that will be use for all values returned by ``#asArray``.
+     * @param prefix a prefix that will be use for all values returned by `#asArray`.
      */
     constructor(...prefix: number[]) {
         this.prefix = prefix;
     }
 
     /**
-     * @param first  the first element of the array to be returned (after the ``prefix`` provided at construction time).
+     * @param first  the first element of the array to be returned (after the `prefix` provided at construction time).
      * @param others other elements to be included in the array.
      */
     public asArray(first: number, ...others: number[]): number[] {
@@ -1283,7 +1283,7 @@ export interface LoadBalancedFargateServiceProps {
  * Helps ensure the JSII kernel & runtime cooperate correctly when an un-exported instance of a class is returned with
  * a declared type that is an exported interface, and the instance inherits from an exported class.
  *
- * @returns an instance of an un-exported class that extends ``ExportedBaseClass``, declared as ``IPrivatelyImplemented``.
+ * @returns an instance of an un-exported class that extends `ExportedBaseClass`, declared as `IPrivatelyImplemented`.
  *
  * @see https://github.com/awslabs/jsii/issues/320
  */

packages/jsii-calc-lib/lib/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Here's the first line of the TSDoc comment.
+ *
+ * This is the meat of the TSDoc comment. It may contain
+ * multiple lines and multiple paragraphs.
+ *
+ * Multiple paragraphs are separated by an empty line.
+ *
+ * @stable
+ */
+export class DocumentedClass {
+
+  /**
+   * Greet the indicated person.
+   *
+   * This will print out a friendly greeting intended for
+   * the indicated person.
+   *
+   * @param greetee The person to be greeted.
+   * @returns A number that everyone knows very well
+   */
+  public greet(greetee: Greetee = {}) {
+    process.stdout.write(`Hello, ${greetee.name || 'world'}\n`);
+    return 42;
+  }
+
+  /**
+   * Say ¡Hola!
+   *
+   * @experimental
+   */
+  public hola() {
+    process.stdout.write('bonjour');
+  }
+}
+
+/**
+ * These are some arguments you can pass to a method.
+ */
+export interface Greetee {
+  /**
+   * The name of the greetee
+   *
+   * @default world
+   */
+  readonly name?: string;
+}
+
+/**
+ * Old class
+ *
+ * @deprecated Use the new class
+ */
+export class Old {
+  /**
+   * Doo wop that thing
+   */
+  public doAThing() {
+    // Nothing to do
+  }
+}

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

@@ -1,2 +1,3 @@
 export * from './calculator';
 export * from './compliance';
+export * from './documented';