feat(java): Indicate if method param is required (#762)

This commit enhances javadoc generation for Java classes so that required
method/constructor parameters are indicated in their description in the javadoc.

This makes it easy for customers to see which paramaters must be provided when
interacting with libraries from Java.

Fixes #365

Author: dagnir

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

@@ -896,11 +896,8 @@ class JavaGenerator extends Generator {
             this.code.line();
             this.code.line('/**');
             this.code.line(` * Sets the value of ${prop.propName}`);
-            if (prop.docs && prop.docs.summary) {
-                this.code.line(` * @param ${prop.fieldName} ${prop.docs.summary}`);
-            } else {
-                this.code.line(` * @param ${prop.fieldName} the value to be set`);
-            }
+            const summary = (prop.docs && prop.docs.summary) || "the value to be set";
+            this.code.line(` * ${paramJavadoc(prop.fieldName, prop.nullable, summary)}`);
             this.code.line(` * @return {@code this}`);
             if (prop.docs && prop.docs.deprecated) {
                 this.code.line(` * @deprecated ${prop.docs.deprecated}`);
@@ -1194,9 +1191,8 @@ class JavaGenerator extends Generator {
             const method = doc as spec.Method;
             if (method.parameters) {
                 for (const param of method.parameters) {
-                    if (param.docs && param.docs.summary) {
-                        tagLines.push(`@param ${param.name} ${param.docs.summary}`);
-                    }
+                    const summary = (param.docs && param.docs.summary) || undefined;
+                    tagLines.push(paramJavadoc(param.name, param.optional, summary));
                 }
             }
         }
@@ -1543,3 +1539,18 @@ function isNullable(optionalValue: spec.OptionalValue | undefined): boolean {
         || (spec.isPrimitiveTypeReference(optionalValue.type)
             && optionalValue.type.primitive === spec.PrimitiveType.Any);
 }
+
+function paramJavadoc(name: string, optional?: boolean, summary?: string): string {
+    const parts = ['@param', name];
+    if (summary) { parts.push(endWithPeriod(summary)); }
+    if (!optional) { parts.push('This parameter is required.'); }
+
+    return parts.join(' ');
+}
+
+function endWithPeriod(s: string): string {
+    if (!s.endsWith('.')) {
+        return s + '.';
+    }
+    return s;
+}

packages/jsii-pacmak/test/expected.jsii-calc-base/java/src/main/java/software/amazon/jsii/tests/calculator/base/BaseProps.java

@@ -20,7 +20,7 @@ public static final class Builder {
 
         /**
          * Sets the value of Bar
-         * @param bar the value to be set
+         * @param bar the value to be set. This parameter is required.
          * @return {@code this}
          */
         public Builder bar(java.lang.String bar) {
@@ -30,7 +30,7 @@ public Builder bar(java.lang.String bar) {
 
         /**
          * Sets the value of Foo
-         * @param foo the value to be set
+         * @param foo the value to be set. This parameter is required.
          * @return {@code this}
          */
         public Builder foo(software.amazon.jsii.tests.calculator.baseofbase.Very foo) {

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/MyFirstStruct.java

@@ -48,7 +48,7 @@ public static final class Builder {
 
         /**
          * Sets the value of Anumber
-         * @param anumber An awesome number value.
+         * @param anumber An awesome number value. This parameter is required.
          * @return {@code this}
          */
         @Deprecated
@@ -60,7 +60,7 @@ public Builder anumber(java.lang.Number anumber) {
 
         /**
          * Sets the value of Astring
-         * @param astring A string value.
+         * @param astring A string value. This parameter is required.
          * @return {@code this}
          */
         @Deprecated
@@ -72,7 +72,7 @@ public Builder astring(java.lang.String astring) {
 
         /**
          * Sets the value of FirstOptional
-         * @param firstOptional the value to be set
+         * @param firstOptional the value to be set.
          * @return {@code this}
          */
         @Deprecated

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/Number.java

@@ -20,7 +20,7 @@ protected Number(final software.amazon.jsii.JsiiObject.InitializationMode initia
     /**
      * Creates a Number object.
      * 
-     * @param value The number.
+     * @param value The number. This parameter is required.
      */
     @Deprecated
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/StructWithOnlyOptionals.java

@@ -47,7 +47,7 @@ public static final class Builder {
 
         /**
          * Sets the value of Optional1
-         * @param optional1 The first optional!
+         * @param optional1 The first optional!.
          * @return {@code this}
          */
         @Deprecated
@@ -59,7 +59,7 @@ public Builder optional1(java.lang.String optional1) {
 
         /**
          * Sets the value of Optional2
-         * @param optional2 the value to be set
+         * @param optional2 the value to be set.
          * @return {@code this}
          */
         @Deprecated
@@ -71,7 +71,7 @@ public Builder optional2(java.lang.Number optional2) {
 
         /**
          * Sets the value of Optional3
-         * @param optional3 the value to be set
+         * @param optional3 the value to be set.
          * @return {@code this}
          */
         @Deprecated

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AbstractClass.java

@@ -23,6 +23,8 @@ protected AbstractClass() {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param name This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public abstract java.lang.String abstractMethod(final java.lang.String name);
@@ -73,6 +75,8 @@ public java.lang.String getAbstractProperty() {
 
         /**
          * EXPERIMENTAL
+         * 
+         * @param name This parameter is required.
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
         @Override

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Add.java

@@ -23,8 +23,8 @@ protected Add(final software.amazon.jsii.JsiiObject.InitializationMode initializ
      * 
      * EXPERIMENTAL
      * 
-     * @param lhs Left-hand side operand.
-     * @param rhs Right-hand side operand.
+     * @param lhs Left-hand side operand. This parameter is required.
+     * @param rhs Right-hand side operand. This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public Add(final software.amazon.jsii.tests.calculator.lib.Value lhs, final software.amazon.jsii.tests.calculator.lib.Value rhs) {

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AllTypes.java

@@ -28,6 +28,8 @@ public AllTypes() {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param inp This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public void anyIn(final java.lang.Object inp) {
@@ -44,6 +46,8 @@ public java.lang.Object anyOut() {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param value This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public software.amazon.jsii.tests.calculator.StringEnum enumMethod(final software.amazon.jsii.tests.calculator.StringEnum value) {

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AllowedMethodNames.java

@@ -23,6 +23,9 @@ public AllowedMethodNames() {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param _p1 This parameter is required.
+     * @param _p2 This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public void getBar(final java.lang.String _p1, final java.lang.Number _p2) {
@@ -33,6 +36,8 @@ public void getBar(final java.lang.String _p1, final java.lang.Number _p2) {
      * getXxx() is not allowed (see negatives), but getXxx(a, ...) is okay.
      * 
      * EXPERIMENTAL
+     * 
+     * @param withParam This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public java.lang.String getFoo(final java.lang.String withParam) {
@@ -41,6 +46,10 @@ public java.lang.String getFoo(final java.lang.String withParam) {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param _x This parameter is required.
+     * @param _y This parameter is required.
+     * @param _z This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public void setBar(final java.lang.String _x, final java.lang.Number _y, final java.lang.Boolean _z) {
@@ -51,6 +60,9 @@ public void setBar(final java.lang.String _x, final java.lang.Number _y, final j
      * setFoo(x) is not allowed (see negatives), but setXxx(a, b, ...) is okay.
      * 
      * EXPERIMENTAL
+     * 
+     * @param _x This parameter is required.
+     * @param _y This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public void setFoo(final java.lang.String _x, final java.lang.Number _y) {

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AsyncVirtualMethods.java

@@ -63,6 +63,8 @@ public java.lang.Number dontOverrideMe() {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param mult This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public java.lang.Number overrideMe(final java.lang.Number mult) {