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

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) {

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

@@ -23,8 +23,8 @@ protected BinaryOperation(final software.amazon.jsii.JsiiObject.InitializationMo
      * 
      * 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)
     protected BinaryOperation(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/Calculator.java

@@ -46,6 +46,8 @@ public Calculator() {
      * Adds a number to the current value.
      * 
      * EXPERIMENTAL
+     * 
+     * @param value This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public void add(final java.lang.Number value) {
@@ -56,6 +58,8 @@ public void add(final java.lang.Number value) {
      * Multiplies the current value by a number.
      * 
      * EXPERIMENTAL
+     * 
+     * @param value This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public void mul(final java.lang.Number value) {
@@ -76,6 +80,8 @@ public void neg() {
      * Raises the current value by a power.
      * 
      * EXPERIMENTAL
+     * 
+     * @param value This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public void pow(final java.lang.Number value) {

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

@@ -38,7 +38,7 @@ public static final class Builder {
 
         /**
          * Sets the value of InitialValue
-         * @param initialValue the value to be set
+         * @param initialValue the value to be set.
          * @return {@code this}
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
@@ -49,7 +49,7 @@ public Builder initialValue(java.lang.Number initialValue) {
 
         /**
          * Sets the value of MaximumValue
-         * @param maximumValue the value to be set
+         * @param maximumValue the value to be set.
          * @return {@code this}
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)

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

@@ -18,6 +18,9 @@ protected ClassWithCollections(final software.amazon.jsii.JsiiObject.Initializat
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param map This parameter is required.
+     * @param array This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public ClassWithCollections(final java.util.Map<java.lang.String, java.lang.String> map, final java.util.List<java.lang.String> array) {

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

@@ -18,6 +18,8 @@ protected ClassWithJavaReservedWords(final software.amazon.jsii.JsiiObject.Initi
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param int This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public ClassWithJavaReservedWords(final java.lang.String intValue) {
@@ -27,6 +29,8 @@ public ClassWithJavaReservedWords(final java.lang.String intValue) {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param assert This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public java.lang.String doImport(final java.lang.String assertValue) {

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

@@ -20,6 +20,9 @@ protected ClassWithPrivateConstructorAndAutomaticProperties(final software.amazo
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param readOnlyString This parameter is required.
+     * @param readWriteString This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public static software.amazon.jsii.tests.calculator.ClassWithPrivateConstructorAndAutomaticProperties create(final java.lang.String readOnlyString, final java.lang.String readWriteString) {

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

@@ -18,6 +18,8 @@ protected ConstructorPassesThisOut(final software.amazon.jsii.JsiiObject.Initial
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param consumer This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public ConstructorPassesThisOut(final software.amazon.jsii.tests.calculator.PartiallyInitializedThisConsumer consumer) {

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

@@ -23,6 +23,8 @@ public ConsumersOfThisCrazyTypeSystem() {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param obj This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public java.lang.String consumeAnotherPublicInterface(final software.amazon.jsii.tests.calculator.IAnotherPublicInterface obj) {
@@ -31,6 +33,8 @@ public java.lang.String consumeAnotherPublicInterface(final software.amazon.jsii
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param obj This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public java.lang.Object consumeNonInternalInterface(final software.amazon.jsii.tests.calculator.INonInternalInterface obj) {

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

@@ -29,6 +29,8 @@ public DataRenderer() {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param data
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public java.lang.String render(final software.amazon.jsii.tests.calculator.lib.MyFirstStruct data) {
@@ -45,6 +47,8 @@ public java.lang.String render() {
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param data This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public java.lang.String renderArbitrary(final java.util.Map<java.lang.String, java.lang.Object> data) {
@@ -53,6 +57,8 @@ public java.lang.String renderArbitrary(final java.util.Map<java.lang.String, ja
 
     /**
      * EXPERIMENTAL
+     * 
+     * @param map This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
     public java.lang.String renderMap(final java.util.Map<java.lang.String, java.lang.Object> map) {