fix(java): missing remarks in builder documentation (#1111)

The Javadoc entries for setting methods on the generated `Builder` classes did not represent the `remarks` section of the `docs` object, resulting in only partial documentation being available on the builders. This makes sure the `remarks` section gets rendered correctly in all the locations that previously ignored it, and the fix is demonstrated good by virtue of the changes it induced in the regression test improvements. Fixes #1094
aws · Dec 10, 2019 · 33e820c · 33e820c
1 parent c19a340
commit 33e820c
Show file tree

Hide file tree

Showing 45 changed files with 242 additions and 130 deletions.
diff --git a/packages/jsii-calc/lib/calculator.ts b/packages/jsii-calc/lib/calculator.ts
@@ -232,8 +232,21 @@ export class Power extends composition.CompositeOperation {
  * Properties for Calculator.
  */
 export interface CalculatorProps {
-    readonly initialValue?: number
-    readonly maximumValue?: number
+    /**
+     * The initial value of the calculator.
+     *
+     * NOTE: Any number works here, it's fine.
+     *
+     * @default 0
+     */
+    readonly initialValue?: number;
+
+    /**
+     * The maximum value the calculator can store.
+     *
+     * @default none
+     */
+    readonly maximumValue?: number;
 }
 
 /**

diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
@@ -1422,7 +1422,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/calculator.ts",
-        "line": 260
+        "line": 273
       },
       "methods": [
         {
@@ -1432,7 +1432,7 @@
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 299
+            "line": 312
           },
           "name": "add",
           "parameters": [
@@ -1451,7 +1451,7 @@
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 306
+            "line": 319
           },
           "name": "mul",
           "parameters": [
@@ -1470,7 +1470,7 @@
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 320
+            "line": 333
           },
           "name": "neg"
         },
@@ -1481,7 +1481,7 @@
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 313
+            "line": 326
           },
           "name": "pow",
           "parameters": [
@@ -1500,7 +1500,7 @@
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 339
+            "line": 352
           },
           "name": "readUnionValue",
           "returns": {
@@ -1520,7 +1520,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 327
+            "line": 340
           },
           "name": "expression",
           "overrides": "jsii-calc.composition.CompositeOperation",
@@ -1536,7 +1536,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 289
+            "line": 302
           },
           "name": "operationsLog",
           "type": {
@@ -1556,7 +1556,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 284
+            "line": 297
           },
           "name": "operationsMap",
           "type": {
@@ -1580,7 +1580,7 @@
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 279
+            "line": 292
           },
           "name": "curr",
           "type": {
@@ -1594,7 +1594,7 @@
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 294
+            "line": 307
           },
           "name": "maxValue",
           "optional": true,
@@ -1609,7 +1609,7 @@
           },
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 334
+            "line": 347
           },
           "name": "unionProperty",
           "optional": true,
@@ -1649,12 +1649,15 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "default": "0",
+            "remarks": "NOTE: Any number works here, it's fine.",
+            "stability": "experimental",
+            "summary": "The initial value of the calculator."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 235
+            "line": 242
           },
           "name": "initialValue",
           "optional": true,
@@ -1665,12 +1668,14 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "default": "none",
+            "stability": "experimental",
+            "summary": "The maximum value the calculator can store."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "lib/calculator.ts",
-            "line": 236
+            "line": 249
           },
           "name": "maximumValue",
           "optional": true,
@@ -11743,5 +11748,5 @@
     }
   },
   "version": "0.20.8",
-  "fingerprint": "w4S74J2aEQiII5p1/vLG5rXFrtvbxUP1mra7ZGBd4so="
+  "fingerprint": "sZ6Jp7HsZKHGh8JYB08PYxyFX0bYBgK1FMDhzjtPjVQ="
 }
diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
@@ -1156,6 +1156,7 @@ class JavaGenerator extends Generator {
       const setter: spec.Method = {
         name: fieldName,
         docs: {
+          ...prop.spec.docs,
           stability: prop.spec.docs?.stability,
           returns: '{@code this}',
         },
@@ -1207,13 +1208,20 @@ class JavaGenerator extends Generator {
     this.code.closeBlock();
   }
 
-  private emitBuilderSetter(prop: JavaProp, builderName: string) {
+  private emitBuilderSetter(prop: JavaProp, builderName: string, builtType: string) {
     for (const type of prop.javaTypes) {
       this.code.line();
       this.code.line('/**');
-      this.code.line(` * Sets the value of ${prop.propName}`);
+      this.code.line(` * Sets the value of {@link ${builtType}#${getterFor(prop.fieldName)}}`);
       const summary = prop.docs?.summary ?? 'the value to be set';
       this.code.line(` * ${paramJavadoc(prop.fieldName, prop.nullable, summary)}`);
+      if (prop.docs?.remarks != null) {
+        const indent = ' '.repeat(7 + prop.fieldName.length);
+        const remarks = md2html(prefixMarkdownTsCodeBlocks(prop.docs.remarks, SAMPLES_DISCLAIMER)).trimRight();
+        for (const line of remarks.split('\n')) {
+          this.code.line(` * ${indent} ${line}`);
+        }
+      }
       this.code.line(' * @return {@code this}');
       if (prop.docs?.deprecated) {
         this.code.line(` * @deprecated ${prop.docs.deprecated}`);
@@ -1225,6 +1233,11 @@ class JavaGenerator extends Generator {
       this.code.line('return this;');
       this.code.closeBlock();
     }
+
+    function getterFor(fieldName: string): string {
+      const [first, ...rest] = fieldName;
+      return `get${first.toUpperCase()}${rest.join('')}`;
+    }
   }
 
   private emitInterfaceBuilder(classSpec: spec.InterfaceType, constructorName: string, props: JavaProp[]) {
@@ -1247,7 +1260,7 @@ class JavaGenerator extends Generator {
     this.code.openBlock(`public static final class ${BUILDER_CLASS_NAME}`);
 
     props.forEach(prop => this.code.line(`private ${prop.fieldJavaType} ${prop.fieldName};`));
-    props.forEach(prop => this.emitBuilderSetter(prop, BUILDER_CLASS_NAME));
+    props.forEach(prop => this.emitBuilderSetter(prop, BUILDER_CLASS_NAME, classSpec.name));
 
     // Start build()
     this.code.line();
@@ -1879,6 +1892,7 @@ function paramJavadoc(name: string, optional?: boolean, summary?: string): strin
 }
 
 function endWithPeriod(s: string): string {
+  s = s.trimRight();
   if (!s.endsWith('.')) {
     return `${s}.`;
   }

diff --git a/...se/java/src/main/java/software/amazon/jsii/tests/calculator/baseofbase/VeryBaseProps.java b/...se/java/src/main/java/software/amazon/jsii/tests/calculator/baseofbase/VeryBaseProps.java
@@ -20,7 +20,7 @@ public static final class Builder {
         private software.amazon.jsii.tests.calculator.baseofbase.Very foo;
 
         /**
-         * Sets the value of Foo
+         * Sets the value of {@link VeryBaseProps#getFoo}
          * @param foo the value to be set. This parameter is required.
          * @return {@code this}
          */

diff --git a/...ii-calc-base/java/src/main/java/software/amazon/jsii/tests/calculator/base/BaseProps.java b/...ii-calc-base/java/src/main/java/software/amazon/jsii/tests/calculator/base/BaseProps.java
@@ -21,7 +21,7 @@ public static final class Builder {
         private software.amazon.jsii.tests.calculator.baseofbase.Very foo;
 
         /**
-         * Sets the value of Bar
+         * Sets the value of {@link BaseProps#getBar}
          * @param bar the value to be set. This parameter is required.
          * @return {@code this}
          */
@@ -31,7 +31,7 @@ public Builder bar(java.lang.String bar) {
         }
 
         /**
-         * Sets the value of Foo
+         * Sets the value of {@link BaseProps#getFoo}
          * @param foo the value to be set. This parameter is required.
          * @return {@code this}
          */

diff --git a/...-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/MyFirstStruct.java b/...-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/MyFirstStruct.java
@@ -51,7 +51,7 @@ public static final class Builder {
         private java.util.List<java.lang.String> firstOptional;
 
         /**
-         * Sets the value of Anumber
+         * Sets the value of {@link MyFirstStruct#getAnumber}
          * @param anumber An awesome number value. This parameter is required.
          * @return {@code this}
          */
@@ -63,7 +63,7 @@ public Builder anumber(java.lang.Number anumber) {
         }
 
         /**
-         * Sets the value of Astring
+         * Sets the value of {@link MyFirstStruct#getAstring}
          * @param astring A string value. This parameter is required.
          * @return {@code this}
          */
@@ -75,7 +75,7 @@ public Builder astring(java.lang.String astring) {
         }
 
         /**
-         * Sets the value of FirstOptional
+         * Sets the value of {@link MyFirstStruct#getFirstOptional}
          * @param firstOptional the value to be set.
          * @return {@code this}
          */

diff --git a/...java/src/main/java/software/amazon/jsii/tests/calculator/lib/StructWithOnlyOptionals.java b/...java/src/main/java/software/amazon/jsii/tests/calculator/lib/StructWithOnlyOptionals.java
@@ -54,7 +54,7 @@ public static final class Builder {
         private java.lang.Boolean optional3;
 
         /**
-         * Sets the value of Optional1
+         * Sets the value of {@link StructWithOnlyOptionals#getOptional1}
          * @param optional1 The first optional!.
          * @return {@code this}
          */
@@ -66,7 +66,7 @@ public Builder optional1(java.lang.String optional1) {
         }
 
         /**
-         * Sets the value of Optional2
+         * Sets the value of {@link StructWithOnlyOptionals#getOptional2}
          * @param optional2 the value to be set.
          * @return {@code this}
          */
@@ -78,7 +78,7 @@ public Builder optional2(java.lang.Number optional2) {
         }
 
         /**
-         * Sets the value of Optional3
+         * Sets the value of {@link StructWithOnlyOptionals#getOptional3}
          * @param optional3 the value to be set.
          * @return {@code this}
          */