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.

Sign up for GitHub

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

[TW-400] Update comments for ForageSDK #153

Merged
merged 7 commits into from
Jan 16, 2024
Merged

[TW-400] Update comments for ForageSDK #153

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cdce816
Update comments for ForageSDK.kt
kimberleehowley Jan 9, 2024
b60df6b
Address PR feedback
kimberleehowley Jan 12, 2024
e54947e
Update example ebt error
kimberleehowley Jan 12, 2024
8e9dae1
Add PR feedback
kimberleehowley Jan 13, 2024
fdce299
Merge branch 'main' into kimberlee/tw-400-update-comments-for-foragesdk
kimberleehowley Jan 13, 2024
30a920c
Attempt to fix linting
kimberleehowley Jan 13, 2024
bdc9211
Typo
kimberleehowley Jan 16, 2024
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
60 changes: 28 additions & 32 deletions forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,16 @@ import com.joinforage.forage.android.ui.ForageConfig
import java.util.UUID

/**
* An instance of the ForageSDK
* Entry point to the Forage SDK.
*
* A [ForageSDK] instance interacts with the Forage API.
*
* You need an instance of the ForageSDK to perform operations like:
*
* * [capturePayment]
* * [checkBalance]
* * [deferPaymentCapture]
* * [tokenizeEBTCard]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we put this in the common order (tokenize -> checkBalance -> deferPaymentCapture -> capturePayment) these and hyperlink them with descriptions?

Suggested change
* * [capturePayment]
* * [checkBalance]
* * [deferPaymentCapture]
* * [tokenizeEBTCard]
* * [Tokenizing card information][tokenizeCard]
* * [Checking the balance of a card][checkBalance]
* * [Collecting a customer's PIN for a payment and deferring the capture of the payment to the server][deferPaymentCapture]
* * [Immediately capturing a payment][capturePayment]

*/
class ForageSDK : ForageSDKInterface {

Expand All @@ -47,13 +56,10 @@ class ForageSDK : ForageSDKInterface {
/**
* Tokenizes an EBT Card via a [ForagePANEditText][com.joinforage.forage.android.ui.ForagePANEditText] Element.
djoksimo marked this conversation as resolved.
Show resolved Hide resolved
*
* @param TokenizeEBTCardParams A model that passes a [`foragePanEditText`][com.joinforage.forage.android.ui.ForagePANEditText] instance, `customerId`, and `reusable` as the [TokenizeEBTCardParams] that Forage uses to tokenize an EBT Card.
* @return A [ForageApiResponse] object.
*
* On success, the object includes a `ref` token that represents an instance of a Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). You can store the token for future transactions, like to [`checkBalance`](checkBalance) or to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in Forage's database.
*
* On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
* @param TokenizeEBTCardParams A model that passes a [`foragePanEditText`][com.joinforage.forage.android.ui.ForagePANEditText] instance, `customerId`, and `reusable` boolean as the [TokenizeEBTCardParams] that Forage uses to tokenize an EBT Card.
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePanEditText`.
* @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling
* @return A [ForageApiResponse] object. On success, the object includes a `ref` token that represents an instance of a Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). You can store the token for future transactions, like to [`checkBalance`](checkBalance) or to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in Forage's database. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
*/
override suspend fun tokenizeEBTCard(params: TokenizeEBTCardParams): ForageApiResponse<String> {
val (foragePanEditText, customerId, reusable) = params
Expand Down Expand Up @@ -87,15 +93,13 @@ class ForageSDK : ForageSDKInterface {
}

/**
* Checks the balance of an EBT Card via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element.
* Checks the balance of a previously created [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To address the issue involving the lack of newlines. What are your thoughts on the following list item-based workaround for the submit methods in this file?

Also:

  • can we wrap long lines to fit roughly inside the right-hand vertical line in Android studio (around 100 character line length limit)
    • the comments should be digestible for clients reading the comments inside Android Studio, and not just the docs site.
  • can we use the notation @param <parameter-name-not-type-here> Description with reference to type of parameter here (as seen in the example below). Sticking with the KDoc standard should reduce the risk of our Dokka breaking and should provide a more familiar + consistent format throughout our comments.
    /**
     * Checks the balance of a previously created [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods)
     * via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element.
     *
     * * On success, the response includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances.
     * * On failure, for example in the case of [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14), 
     * the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
     *
     * @param params A [CheckBalanceParams][com.joinforage.forage.android.network.model] model
     * that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance
     * and a `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method) endpoint.
     * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`.
     * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling.
     * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#balance-inquiry-exceptions) to trigger balance inquiry exceptions during testing.
     * @return A [ForageApiResponse] object.
     */
image

*
* @param CheckBalanceParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method) endpoint, as the [CheckBalanceParams] that Forage uses to check the balance of an EBT Card.
* @return A [ForageApiResponse] object.
*
* On success, the object includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances.
*
* On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
* @param CheckBalanceParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method) endpoint, as the [CheckBalanceParams].
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`.
* @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling.
* * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#balance-inquiry-exceptions) to trigger balance inquiry exceptions during testing.
* @return A [ForageApiResponse] object. On success, the object includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
*/
override suspend fun checkBalance(params: CheckBalanceParams): ForageApiResponse<String> {
val (foragePinEditText, paymentMethodRef) = params
Expand Down Expand Up @@ -173,15 +177,13 @@ class ForageSDK : ForageSDKInterface {
}

/**
* Captures a payment via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element.
* Immediately captures a payment via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element.
*
* @param CapturePaymentParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [CapturePaymentParams] that Forage uses to capture a payment.
* @return A [ForageApiResponse] object.
*
* On success, the object confirms the transaction.
*
* On failure, the object includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
* @param CapturePaymentParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [CapturePaymentParams] that Forage uses to capture a payment.
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`.
* @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling.
* * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#payment-capture-exceptions) to trigger payment capture exceptions during testing.
* @return A [ForageApiResponse] object. On success, the object confirms the transaction. The response includes a Forage [`Payment`](https://docs.joinforage.app/reference/payments) object. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
*/
override suspend fun capturePayment(params: CapturePaymentParams): ForageApiResponse<String> {
val (foragePinEditText, paymentRef) = params
Expand Down Expand Up @@ -273,17 +275,11 @@ class ForageSDK : ForageSDKInterface {
*
* @param DeferPaymentCaptureParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [DeferPaymentCaptureParams].
kimberleehowley marked this conversation as resolved.
Show resolved Hide resolved
*
* @return A [ForageApiResponse] object.
*
* On success, the object returns `Nothing`.
*
* On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`.
*
* @see
* [Defer EBT payment capture to the server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side) for the related step-by-step guide.
*
* [Capture an EBT Payment](https://docs.joinforage.app/reference/capture-a-payment) for the related endpoint.
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`.
* @see * [Defer EBT payment capture to the server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side) for the related step-by-step guide.
* * [Capture an EBT Payment](https://docs.joinforage.app/reference/capture-a-payment) for the API endpoint to call after [deferPaymentCapture].
* * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling.
* @return A [ForageApiResponse] object. On success, the object returns `Nothing`. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue.
*/
override suspend fun deferPaymentCapture(params: DeferPaymentCaptureParams): ForageApiResponse<String> {
val (foragePinEditText, paymentRef) = params
Expand Down