docs: add more documentation (#205)

Author: stainless-app[bot]

buildSrc/src/main/kotlin/orb.kotlin.gradle.kts

@@ -21,8 +21,12 @@ configure<SpotlessExtension> {
 
 tasks.withType<KotlinCompile>().configureEach {
     kotlinOptions {
-        allWarningsAsErrors = true
-        freeCompilerArgs = listOf("-Xjvm-default=all", "-Xjdk-release=1.8")
+        freeCompilerArgs = listOf(
+          "-Xjvm-default=all",
+          "-Xjdk-release=1.8",
+          // Suppress deprecation warnings because we may still reference and test deprecated members.
+          "-Xsuppress-warning=DEPRECATION"
+        )
         jvmTarget = "1.8"
     }
 }

orb-java-core/src/main/kotlin/com/withorb/api/models/Alert.kt

@@ -915,6 +915,7 @@ private constructor(
             "Threshold{value=$value, additionalProperties=$additionalProperties}"
     }
 
+    /** The type of alert. This must be a valid alert type. */
     class Type
     @JsonCreator
     private constructor(

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForCustomerParams.kt

@@ -414,6 +414,7 @@ constructor(
             )
     }
 
+    /** The type of alert to create. This must be a valid alert type. */
     class Type
     @JsonCreator
     private constructor(

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForExternalCustomerParams.kt

@@ -423,6 +423,7 @@ constructor(
             )
     }
 
+    /** The type of alert to create. This must be a valid alert type. */
     class Type
     @JsonCreator
     private constructor(

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForSubscriptionParams.kt

@@ -534,6 +534,7 @@ constructor(
             "Threshold{value=$value, additionalProperties=$additionalProperties}"
     }
 
+    /** The type of alert to create. This must be a valid alert type. */
     class Type
     @JsonCreator
     private constructor(

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertListPage.kt

@@ -19,6 +19,17 @@ import java.util.Optional
 import java.util.stream.Stream
 import java.util.stream.StreamSupport
 
+/**
+ * This endpoint returns a list of alerts within Orb.
+ *
+ * The request must specify one of `customer_id`, `external_customer_id`, or `subscription_id`.
+ *
+ * If querying by subscripion_id, the endpoint will return the subscription level alerts as well as
+ * the plan level alerts associated with the subscription.
+ *
+ * The list of alerts is ordered starting from the most recently created alert. This endpoint
+ * follows Orb's [standardized pagination format](../reference/pagination).
+ */
 class AlertListPage
 private constructor(
     private val alertsService: AlertService,

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertListPageAsync.kt

@@ -20,6 +20,17 @@ import java.util.concurrent.CompletableFuture
 import java.util.concurrent.Executor
 import java.util.function.Predicate
 
+/**
+ * This endpoint returns a list of alerts within Orb.
+ *
+ * The request must specify one of `customer_id`, `external_customer_id`, or `subscription_id`.
+ *
+ * If querying by subscripion_id, the endpoint will return the subscription level alerts as well as
+ * the plan level alerts associated with the subscription.
+ *
+ * The list of alerts is ordered starting from the most recently created alert. This endpoint
+ * follows Orb's [standardized pagination format](../reference/pagination).
+ */
 class AlertListPageAsync
 private constructor(
     private val alertsService: AlertServiceAsync,

orb-java-core/src/main/kotlin/com/withorb/api/models/CouponListPage.kt

@@ -19,6 +19,13 @@ import java.util.Optional
 import java.util.stream.Stream
 import java.util.stream.StreamSupport
 
+/**
+ * This endpoint returns a list of all coupons for an account in a list format.
+ *
+ * The list of coupons is ordered starting from the most recently created coupon. The response also
+ * includes `pagination_metadata`, which lets the caller retrieve the next page of results if they
+ * exist. More information about pagination can be found in the Pagination-metadata schema.
+ */
 class CouponListPage
 private constructor(
     private val couponsService: CouponService,

orb-java-core/src/main/kotlin/com/withorb/api/models/CouponListPageAsync.kt

@@ -20,6 +20,13 @@ import java.util.concurrent.CompletableFuture
 import java.util.concurrent.Executor
 import java.util.function.Predicate
 
+/**
+ * This endpoint returns a list of all coupons for an account in a list format.
+ *
+ * The list of coupons is ordered starting from the most recently created coupon. The response also
+ * includes `pagination_metadata`, which lets the caller retrieve the next page of results if they
+ * exist. More information about pagination can be found in the Pagination-metadata schema.
+ */
 class CouponListPageAsync
 private constructor(
     private val couponsService: CouponServiceAsync,

orb-java-core/src/main/kotlin/com/withorb/api/models/CouponSubscriptionListPage.kt

@@ -19,6 +19,12 @@ import java.util.Optional
 import java.util.stream.Stream
 import java.util.stream.StreamSupport
 
+/**
+ * This endpoint returns a list of all subscriptions that have redeemed a given coupon as a
+ * [paginated](../reference/pagination) list, ordered starting from the most recently created
+ * subscription. For a full discussion of the subscription resource, see
+ * [Subscription](../guides/concepts#subscription).
+ */
 class CouponSubscriptionListPage
 private constructor(
     private val subscriptionsService: SubscriptionService,