Verify v1 KDocs

CHANGELOG.md

@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 GA release!
 
 ### Added
-- Documentation (KDocs) for all classes and methods
+- Documentation (KDocs) for all classes and methods.
 
 ## [1.0.0-beta1] - 2024-09-02
 Feature-complete beta release.
@@ -17,7 +17,10 @@ Feature-complete beta release.
 - Video API
 
 ### Changed
-- Standardised `Existing*` classes to extend `ExistingResource` for consistency
+- Renamed `VerifyLegacy.ExistingRequest#search` to `info` for consistency with other APIs.
+
+### Changed
+- Standardised `Existing*` classes to extend `ExistingResource` for consistency.
 
 ## [0.9.0] - 2024-08-19
 
@@ -36,8 +39,8 @@ Feature-complete beta release.
 - Account API
 
 ### Changed
-- Explicit return types for all methods
-- Introduced `ExistingRequest` class to Verify (v2) to reduce duplicating `requestId` parameter
+- Explicit return types for all methods.
+- Introduced `ExistingRequest` class to Verify (v2) to reduce duplicating `requestId` parameter.
 
 ## [0.6.0] - 2024-07-30
 
@@ -46,8 +49,8 @@ Feature-complete beta release.
 - Number Verification API
 
 ### Changed
-- `InputAction.Builder#dtmf` extension method uses `DtmfSettings` builder instead of setters
-- `Messages#send` now uses optional Boolean parameter for sandbox instead of separate method
+- `InputAction.Builder#dtmf` extension method uses `DtmfSettings` builder instead of setters.
+- `Messages#send` now uses optional Boolean parameter for sandbox instead of separate method.
 
 ## [0.5.0] - 2024-07-25
 
@@ -62,7 +65,7 @@ Feature-complete beta release.
 ## [0.3.1] - 2024-07-12
 
 ### Changed
-- Upgraded Java SDK version to 8.9.2
+- Upgraded Java SDK version to 8.9.2.
 
 ## [0.3.0] - 2024-07-08
 
@@ -81,7 +84,7 @@ Feature-complete beta release.
 - Voice API
 
 ### Fixed
-- `authFromEnv` now checks for absent environment variables before attempting to set them
+- `authFromEnv` now checks for absent environment variables before attempting to set them.
 
 ## [0.1.0] - 2024-06-25
 Initial version.

src/main/kotlin/com/vonage/client/kt/VerifyLegacy.kt

@@ -24,27 +24,94 @@ import com.vonage.client.verify.*
  */
 class VerifyLegacy internal constructor(private val client: VerifyClient) {
 
+    /**
+     * Initiate a verification request.
+     *
+     * @param number The phone number to verify in E.164 format.
+     *
+     * @param brand The name of the company or app sending the verification request.
+     * This is what the user will see the sender as on their device.
+     *
+     * @param properties A lambda function for specifying additional parameters of the request.
+     *
+     * @return A [VerifyResponse] object containing the request ID and status.
+     */
     fun verify(number: String, brand: String, properties: (VerifyRequest.Builder.() -> Unit) = {}): VerifyResponse =
         client.verify(VerifyRequest.builder(number, brand).apply(properties).build())
 
+    /**
+     * Generate and send a PIN to your user to authorize a payment, compliant with Payment Services Directive 2.
+     *
+     * @param number The phone number to send the request to, in E.164 format.
+     *
+     * @param amount The decimal amount of the payment to be confirmed, in Euros.
+     *
+     * @param payee Name of the recipient that the user is confirming a payment to.
+     *
+     * @param properties (OPTIONAL) A lambda function for specifying additional parameters of the request.
+     *
+     * @return A [VerifyResponse] object containing the request ID and status.
+     */
     fun psd2Verify(number: String, amount: Double, payee: String,
                    properties: (Psd2Request.Builder.() -> Unit) = {}): VerifyResponse =
         client.psd2Verify(Psd2Request.builder(number, amount, payee).apply(properties).build())
 
+    /**
+     * Use this method to check the status of past or current verification requests.
+     *
+     * @param requestIds One or more request IDs to check.
+     *
+     * @return Information about the verification request(s).
+     *
+     * @see [ExistingRequest.info] An alias for this method.
+     */
     fun search(vararg requestIds: String): SearchVerifyResponse = client.search(*requestIds)
 
-    fun request(requestId: String): ExistingRequest = ExistingRequest(requestId)
-
+    /**
+     * Call this method to work with an existing verification request.
+     *
+     * @param response Response object containing the request ID.
+     */
     fun request(response: VerifyResponse): ExistingRequest = request(response.requestId)
 
+    /**
+     * Call this method to work with an existing verification request.
+     *
+     * @param requestId ID of the verification request to work with.
+     */
+    fun request(requestId: String): ExistingRequest = ExistingRequest(requestId)
+
+    /**
+     * Call this method to work with an existing verification request.
+     *
+     * @param id ID of the verification request to work with.
+     */
     inner class ExistingRequest internal constructor(id: String): ExistingResource(id) {
 
+        /**
+         * Retrieve details about the verification request.
+         *
+         * @return Information about the verification request.
+         *
+         * @see [search] An alias for this method.
+         */
+        fun info(): SearchVerifyResponse = client.search(id)
+
+        /**
+         * Cancel the verification request.
+         */
         fun cancel(): ControlResponse = client.cancelVerification(id)
 
+        /**
+         * Trigger the next verification step.
+         */
         fun advance(): ControlResponse = client.advanceVerification(id)
 
+        /**
+         * Check the verification code.
+         *
+         * @param code PIN code to check, as entered by the user.
+         */
         fun check(code: String): CheckResponse = client.check(id, code)
-
-        fun search(): SearchVerifyResponse = client.search(id)
     }
 }