fix(sdk): javadoc comments

matoous · matoous · commit dfe319b48188 · 2026-01-11T19:21:45.000+01:00
diff --git a/codegen/internal/generator/render.go b/codegen/internal/generator/render.go
@@ -398,6 +398,12 @@ func loadTemplate(name string) (*template.Template, error) {
 	tmpl, err := template.New(name).Funcs(template.FuncMap{
 		"quote": func(s string) string { return strconvQuote(s) },
 		"join":  func(values []string, sep string) string { return strings.Join(values, sep) },
+		"javadocType": func(s string) string {
+			if strings.ContainsAny(s, "<>") {
+				return "{@code " + s + "}"
+			}
+			return s
+		},
 	}).Parse(string(content))
 	if err != nil {
 		return nil, fmt.Errorf("parse template %s: %w", name, err)
diff --git a/codegen/internal/generator/templates/client.tmpl b/codegen/internal/generator/templates/client.tmpl
@@ -53,7 +53,7 @@ public final class {{ .ClassName }} {
 {{- end }}
      * <p>Call the overload that accepts optional parameter objects or RequestOptions to customize headers, authorization, query values, or timeouts.</p>
 {{- if not .ReturnsVoid }}
-     * @return {{ .ResponseType.Name }} parsed response.
+     * @return {{ javadocType .ResponseType.Name }} parsed response.
 {{- end }}
      * @throws ApiException if the SumUp API returns an error.
      */
@@ -99,7 +99,7 @@ public final class {{ .ClassName }} {
 {{- end }}
      * <p>Call the overload that accepts RequestOptions to customize headers, authorization, or request timeout.</p>
 {{- if not .ReturnsVoid }}
-     * @return {{ .ResponseType.Name }} parsed response.
+     * @return {{ javadocType .ResponseType.Name }} parsed response.
 {{- end }}
      * @throws ApiException if the SumUp API returns an error.
      */
@@ -144,7 +144,7 @@ public final class {{ .ClassName }} {
 {{- end }}
      * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass {@code null} to use client defaults.
 {{- if not .ReturnsVoid }}
-     * @return {{ .ResponseType.Name }} parsed response.
+     * @return {{ javadocType .ResponseType.Name }} parsed response.
 {{- end }}
      * @throws ApiException if the SumUp API returns an error.
      */
diff --git a/codegen/internal/generator/templates/client_async.tmpl b/codegen/internal/generator/templates/client_async.tmpl
@@ -53,7 +53,7 @@ public final class {{ .ClassName }} {
 {{- end }}
      * <p>Call the overload that accepts optional parameter objects or RequestOptions to customize headers, authorization, query values, or timeouts.</p>
 {{- if not .ReturnsVoid }}
-     * @return CompletableFuture resolved with {{ .ResponseType.Name }} parsed response.
+     * @return CompletableFuture resolved with {{ javadocType .ResponseType.Name }} parsed response.
 {{- else }}
      * @return CompletableFuture completed when the request finishes.
 {{- end }}
@@ -97,7 +97,7 @@ public final class {{ .ClassName }} {
 {{- end }}
      * <p>Call the overload that accepts RequestOptions to customize headers, authorization, or request timeout.</p>
 {{- if not .ReturnsVoid }}
-     * @return CompletableFuture resolved with {{ .ResponseType.Name }} parsed response.
+     * @return CompletableFuture resolved with {{ javadocType .ResponseType.Name }} parsed response.
 {{- else }}
      * @return CompletableFuture completed when the request finishes.
 {{- end }}
@@ -144,7 +144,7 @@ public final class {{ .ClassName }} {
 {{- end }}
      * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass {@code null} to use client defaults.
 {{- if not .ReturnsVoid }}
-     * @return CompletableFuture resolved with {{ .ResponseType.Name }} parsed response.
+     * @return CompletableFuture resolved with {{ javadocType .ResponseType.Name }} parsed response.
 {{- else }}
      * @return CompletableFuture completed when the request finishes.
 {{- end }}
diff --git a/codegen/internal/generator/templates/model.tmpl b/codegen/internal/generator/templates/model.tmpl
@@ -1,13 +1,14 @@
 // Code generated by sumup-java/codegen. DO NOT EDIT.
 package {{ .Package }};
-{{- if .Imports }}
+{{ if .Imports }}
 {{ range .Imports }}import {{ . }};
-{{- end }}
-{{- end }}
+{{ end }}
+{{ end }}
 
 {{- if .DescriptionLines }}
 /**
-{{ range .DescriptionLines }} * {{ . }}
+{{- range .DescriptionLines }}
+ * {{ . }}
 {{- end }}
  */
 {{- end }}
diff --git a/src/main/java/com/sumup/sdk/clients/CheckoutsAsyncClient.java b/src/main/java/com/sumup/sdk/clients/CheckoutsAsyncClient.java
@@ -269,8 +269,8 @@ public CompletableFuture<com.sumup.sdk.models.GetPaymentMethodsResponse> getPaym
    * <p>Call the overload that accepts optional parameter objects or RequestOptions to customize
    * headers, authorization, query values, or timeouts.
    *
-   * @return CompletableFuture resolved with java.util.List<com.sumup.sdk.models.CheckoutSuccess>
-   *     parsed response.
+   * @return CompletableFuture resolved with {@code
+   *     java.util.List<com.sumup.sdk.models.CheckoutSuccess>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public CompletableFuture<java.util.List<com.sumup.sdk.models.CheckoutSuccess>> listCheckouts()
@@ -288,8 +288,8 @@ public CompletableFuture<java.util.List<com.sumup.sdk.models.CheckoutSuccess>> l
    * @param listCheckouts Optional query parameters for this request.
    *     <p>Call the overload that accepts RequestOptions to customize headers, authorization, or
    *     request timeout.
-   * @return CompletableFuture resolved with java.util.List<com.sumup.sdk.models.CheckoutSuccess>
-   *     parsed response.
+   * @return CompletableFuture resolved with {@code
+   *     java.util.List<com.sumup.sdk.models.CheckoutSuccess>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public CompletableFuture<java.util.List<com.sumup.sdk.models.CheckoutSuccess>> listCheckouts(
@@ -307,8 +307,8 @@ public CompletableFuture<java.util.List<com.sumup.sdk.models.CheckoutSuccess>> l
    * @param listCheckouts Optional query parameters for this request.
    * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass
    *     {@code null} to use client defaults.
-   * @return CompletableFuture resolved with java.util.List<com.sumup.sdk.models.CheckoutSuccess>
-   *     parsed response.
+   * @return CompletableFuture resolved with {@code
+   *     java.util.List<com.sumup.sdk.models.CheckoutSuccess>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public CompletableFuture<java.util.List<com.sumup.sdk.models.CheckoutSuccess>> listCheckouts(
diff --git a/src/main/java/com/sumup/sdk/clients/CheckoutsClient.java b/src/main/java/com/sumup/sdk/clients/CheckoutsClient.java
@@ -263,7 +263,7 @@ public com.sumup.sdk.models.GetPaymentMethodsResponse getPaymentMethods(
    * <p>Call the overload that accepts optional parameter objects or RequestOptions to customize
    * headers, authorization, query values, or timeouts.
    *
-   * @return java.util.List<com.sumup.sdk.models.CheckoutSuccess> parsed response.
+   * @return {@code java.util.List<com.sumup.sdk.models.CheckoutSuccess>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public java.util.List<com.sumup.sdk.models.CheckoutSuccess> listCheckouts() throws ApiException {
@@ -280,7 +280,7 @@ public java.util.List<com.sumup.sdk.models.CheckoutSuccess> listCheckouts() thro
    * @param listCheckouts Optional query parameters for this request.
    *     <p>Call the overload that accepts RequestOptions to customize headers, authorization, or
    *     request timeout.
-   * @return java.util.List<com.sumup.sdk.models.CheckoutSuccess> parsed response.
+   * @return {@code java.util.List<com.sumup.sdk.models.CheckoutSuccess>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public java.util.List<com.sumup.sdk.models.CheckoutSuccess> listCheckouts(
@@ -298,7 +298,7 @@ public java.util.List<com.sumup.sdk.models.CheckoutSuccess> listCheckouts(
    * @param listCheckouts Optional query parameters for this request.
    * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass
    *     {@code null} to use client defaults.
-   * @return java.util.List<com.sumup.sdk.models.CheckoutSuccess> parsed response.
+   * @return {@code java.util.List<com.sumup.sdk.models.CheckoutSuccess>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public java.util.List<com.sumup.sdk.models.CheckoutSuccess> listCheckouts(
diff --git a/src/main/java/com/sumup/sdk/clients/CustomersAsyncClient.java b/src/main/java/com/sumup/sdk/clients/CustomersAsyncClient.java
@@ -181,8 +181,8 @@ public CompletableFuture<com.sumup.sdk.models.Customer> getCustomer(
    * @param customerId Unique ID of the saved customer resource.
    *     <p>Call the overload that accepts RequestOptions to customize headers, authorization, or
    *     request timeout.
-   * @return CompletableFuture resolved with
-   *     java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse> parsed response.
+   * @return CompletableFuture resolved with {@code
+   *     java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public CompletableFuture<java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse>>
@@ -200,8 +200,8 @@ public CompletableFuture<com.sumup.sdk.models.Customer> getCustomer(
    * @param customerId Unique ID of the saved customer resource.
    * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass
    *     {@code null} to use client defaults.
-   * @return CompletableFuture resolved with
-   *     java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse> parsed response.
+   * @return CompletableFuture resolved with {@code
+   *     java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public CompletableFuture<java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse>>
diff --git a/src/main/java/com/sumup/sdk/clients/CustomersClient.java b/src/main/java/com/sumup/sdk/clients/CustomersClient.java
@@ -175,7 +175,7 @@ public com.sumup.sdk.models.Customer getCustomer(String customerId, RequestOptio
    * @param customerId Unique ID of the saved customer resource.
    *     <p>Call the overload that accepts RequestOptions to customize headers, authorization, or
    *     request timeout.
-   * @return java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse> parsed response.
+   * @return {@code java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse> listPaymentInstruments(
@@ -193,7 +193,7 @@ public java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse> listPaymen
    * @param customerId Unique ID of the saved customer resource.
    * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass
    *     {@code null} to use client defaults.
-   * @return java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse> parsed response.
+   * @return {@code java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public java.util.List<com.sumup.sdk.models.PaymentInstrumentResponse> listPaymentInstruments(
diff --git a/src/main/java/com/sumup/sdk/clients/SubaccountsAsyncClient.java b/src/main/java/com/sumup/sdk/clients/SubaccountsAsyncClient.java
@@ -181,8 +181,8 @@ public CompletableFuture<com.sumup.sdk.models.Operator> deactivateSubAccount(
    * <p>Call the overload that accepts optional parameter objects or RequestOptions to customize
    * headers, authorization, query values, or timeouts.
    *
-   * @return CompletableFuture resolved with java.util.List<com.sumup.sdk.models.Operator> parsed
-   *     response.
+   * @return CompletableFuture resolved with {@code java.util.List<com.sumup.sdk.models.Operator>}
+   *     parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public CompletableFuture<java.util.List<com.sumup.sdk.models.Operator>> listSubAccounts()
@@ -200,8 +200,8 @@ public CompletableFuture<java.util.List<com.sumup.sdk.models.Operator>> listSubA
    * @param listSubAccounts Optional query parameters for this request.
    *     <p>Call the overload that accepts RequestOptions to customize headers, authorization, or
    *     request timeout.
-   * @return CompletableFuture resolved with java.util.List<com.sumup.sdk.models.Operator> parsed
-   *     response.
+   * @return CompletableFuture resolved with {@code java.util.List<com.sumup.sdk.models.Operator>}
+   *     parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public CompletableFuture<java.util.List<com.sumup.sdk.models.Operator>> listSubAccounts(
@@ -219,8 +219,8 @@ public CompletableFuture<java.util.List<com.sumup.sdk.models.Operator>> listSubA
    * @param listSubAccounts Optional query parameters for this request.
    * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass
    *     {@code null} to use client defaults.
-   * @return CompletableFuture resolved with java.util.List<com.sumup.sdk.models.Operator> parsed
-   *     response.
+   * @return CompletableFuture resolved with {@code java.util.List<com.sumup.sdk.models.Operator>}
+   *     parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public CompletableFuture<java.util.List<com.sumup.sdk.models.Operator>> listSubAccounts(
diff --git a/src/main/java/com/sumup/sdk/clients/SubaccountsClient.java b/src/main/java/com/sumup/sdk/clients/SubaccountsClient.java
@@ -179,7 +179,7 @@ public com.sumup.sdk.models.Operator deactivateSubAccount(
    * <p>Call the overload that accepts optional parameter objects or RequestOptions to customize
    * headers, authorization, query values, or timeouts.
    *
-   * @return java.util.List<com.sumup.sdk.models.Operator> parsed response.
+   * @return {@code java.util.List<com.sumup.sdk.models.Operator>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public java.util.List<com.sumup.sdk.models.Operator> listSubAccounts() throws ApiException {
@@ -196,7 +196,7 @@ public java.util.List<com.sumup.sdk.models.Operator> listSubAccounts() throws Ap
    * @param listSubAccounts Optional query parameters for this request.
    *     <p>Call the overload that accepts RequestOptions to customize headers, authorization, or
    *     request timeout.
-   * @return java.util.List<com.sumup.sdk.models.Operator> parsed response.
+   * @return {@code java.util.List<com.sumup.sdk.models.Operator>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public java.util.List<com.sumup.sdk.models.Operator> listSubAccounts(
@@ -214,7 +214,7 @@ public java.util.List<com.sumup.sdk.models.Operator> listSubAccounts(
    * @param listSubAccounts Optional query parameters for this request.
    * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass
    *     {@code null} to use client defaults.
-   * @return java.util.List<com.sumup.sdk.models.Operator> parsed response.
+   * @return {@code java.util.List<com.sumup.sdk.models.Operator>} parsed response.
    * @throws ApiException if the SumUp API returns an error.
    */
   public java.util.List<com.sumup.sdk.models.Operator> listSubAccounts(
diff --git a/src/main/java/com/sumup/sdk/models/Address.java b/src/main/java/com/sumup/sdk/models/Address.java
@@ -6,7 +6,7 @@
 /**
  * An address somewhere in the world. The address fields used depend on the country conventions. For
  * example, in Great Britain, `city` is `post_town`. In the United States, the top-level
- * administrative unit used in addresses is `state`, whereas in Chile it's `region`. * Whether an
+ * administrative unit used in addresses is `state`, whereas in Chile it's `region`. Whether an
  * address is valid or not depends on whether the locally required fields are present. Fields not
  * supported in a country will be ignored.
  */
diff --git a/src/main/java/com/sumup/sdk/models/Affiliate.java b/src/main/java/com/sumup/sdk/models/Affiliate.java
@@ -4,7 +4,7 @@
 import java.util.Objects;
 
 /**
- * Affiliate metadata for the transaction. * It is a field that allow for integrators to track the
+ * Affiliate metadata for the transaction. It is a field that allow for integrators to track the
  * source of the transaction.
  */
 public record Affiliate(
diff --git a/src/main/java/com/sumup/sdk/models/ChangeStatus.java b/src/main/java/com/sumup/sdk/models/ChangeStatus.java
@@ -4,7 +4,7 @@
 /**
  * Reflects the status of changes submitted through the `PATCH` endpoints for the merchant or
  * persons. If some changes have not been applied yet, the status will be `pending`. If all changes
- * have been applied, the status `done`. * The status is only returned after write operations or on
+ * have been applied, the status `done`. The status is only returned after write operations or on
  * read endpoints when the `version` query parameter is provided.
  */
 public record ChangeStatus(String value) {
diff --git a/src/main/java/com/sumup/sdk/models/CountryCode.java b/src/main/java/com/sumup/sdk/models/CountryCode.java
@@ -2,8 +2,8 @@
 package com.sumup.sdk.models;
 
 /**
- * An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) * country code. This
- * definition users `oneOf` with a two-character string * type to allow for support of future
+ * An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. This
+ * definition users `oneOf` with a two-character string type to allow for support of future
  * countries in client code.
  */
 public record CountryCode(String value) {
diff --git a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestCardType.java b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestCardType.java
@@ -5,8 +5,8 @@
 import com.fasterxml.jackson.annotation.JsonValue;
 
 /**
- * The card type of the card used for the transaction. * Is is required only for some countries
- * (e.g: Brazil).
+ * The card type of the card used for the transaction. Is is required only for some countries (e.g:
+ * Brazil).
  */
 public enum CreateReaderCheckoutRequestCardType {
   CREDIT("credit"),
diff --git a/src/main/java/com/sumup/sdk/models/Meta.java b/src/main/java/com/sumup/sdk/models/Meta.java
@@ -3,7 +3,7 @@
 
 /**
  * A set of key-value pairs that you can attach to an object. This can be useful for storing
- * additional information about the object in a structured format. * **Warning**: Updating Meta will
+ * additional information about the object in a structured format. **Warning**: Updating Meta will
  * overwrite the existing data. Make sure to always include the complete JSON object.
  */
 public record Meta(java.util.Map<String, Object> value) {
diff --git a/src/main/java/com/sumup/sdk/models/Money.java b/src/main/java/com/sumup/sdk/models/Money.java
@@ -4,8 +4,8 @@
 import java.util.Objects;
 
 /**
- * Amount structure. * The amount is represented as an integer value altogether with the currency
- * and the minor unit. * For example, EUR 1.00 is represented as value 100 with minor unit of 2.
+ * Amount structure. The amount is represented as an integer value altogether with the currency and
+ * the minor unit. For example, EUR 1.00 is represented as value 100 with minor unit of 2.
  */
 public record Money(
     /** Currency ISO 4217 code */
diff --git a/src/main/java/com/sumup/sdk/models/Problem.java b/src/main/java/com/sumup/sdk/models/Problem.java
@@ -4,7 +4,7 @@
 import java.util.Objects;
 
 /**
- * A RFC 9457 problem details object. * Additional properties specific to the problem type may be
+ * A RFC 9457 problem details object. Additional properties specific to the problem type may be
  * present.
  */
 public record Problem(
diff --git a/src/main/java/com/sumup/sdk/models/ReaderId.java b/src/main/java/com/sumup/sdk/models/ReaderId.java
@@ -2,7 +2,7 @@
 package com.sumup.sdk.models;
 
 /**
- * Unique identifier of the object. * Note that this identifies the instance of the physical devices
+ * Unique identifier of the object. Note that this identifies the instance of the physical devices
  * pairing with your SumUp account. If you
  * [delete](https://developer.sumup.com/api/readers/delete-reader) a reader, and pair the device
  * again, the ID will be different. Do not use this ID to refer to a physical device.
diff --git a/src/main/java/com/sumup/sdk/models/ReaderStatus.java b/src/main/java/com/sumup/sdk/models/ReaderStatus.java
@@ -5,11 +5,11 @@
 import com.fasterxml.jackson.annotation.JsonValue;
 
 /**
- * The status of the reader object gives information about the current state of the reader. *
- * Possible values: * - `unknown` - The reader status is unknown. * - `processing` - The reader is
- * created and waits for the physical device to confirm the pairing. * - `paired` - The reader is
- * paired with a merchant account and can be used with SumUp APIs. * - `expired` - The pairing is
- * expired and no longer usable with the account. The resource needs to get recreated.
+ * The status of the reader object gives information about the current state of the reader. Possible
+ * values: - `unknown` - The reader status is unknown. - `processing` - The reader is created and
+ * waits for the physical device to confirm the pairing. - `paired` - The reader is paired with a
+ * merchant account and can be used with SumUp APIs. - `expired` - The pairing is expired and no
+ * longer usable with the account. The resource needs to get recreated.
  */
 public enum ReaderStatus {
   UNKNOWN("unknown"),
diff --git a/src/main/java/com/sumup/sdk/models/ResourceType.java b/src/main/java/com/sumup/sdk/models/ResourceType.java
@@ -2,8 +2,8 @@
 package com.sumup.sdk.models;
 
 /**
- * The type of the membership resource. * Possible values are: * * `merchant` - merchant account(s)
- * * * `organization` - organization(s)
+ * The type of the membership resource. Possible values are: * `merchant` - merchant account(s) *
+ * `organization` - organization(s)
  */
 public record ResourceType(String value) {
   /**
