Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
Sep 9, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions packages/jsii-pacmak/lib/targets/java.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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}`);
Expand Down Expand Up @@ -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));
}
}
}
Expand Down Expand Up @@ -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.'); }
eladb marked this conversation as resolved.
Show resolved Hide resolved

return parts.join(' ');
}

function endWithPeriod(s: string): string {
if (!s.endsWith('.')) {
return s + '.';
}
return s;
}
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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) {
Expand All @@ -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) {
Expand All @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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) {
Expand All @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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) {
Expand All @@ -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) {
Expand Down
Loading