Add PHPDoc class descriptions

lib/Account.php

@@ -3,7 +3,13 @@
 namespace Stripe;
 
 /**
- * Class Account.
+ * This is an object representing a Stripe account. You can retrieve it to see
+ * properties on the account like its current e-mail address or if the account is
+ * enabled yet to make live charges.
+ *
+ * Some properties, marked below, are available only to platforms that want to <a
+ * href="https://stripe.com/docs/connect/accounts">create and manage Express or
+ * Custom accounts</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.
@@ -18,7 +24,7 @@
  * @property bool $details_submitted Whether account details have been submitted. Standard accounts cannot receive payouts before this is true.
  * @property null|string $email The primary user's email address.
  * @property \Stripe\Collection $external_accounts External accounts (bank accounts and debit cards) currently attached to this account
- * @property \Stripe\Person $individual
+ * @property \Stripe\Person $individual <p>This is an object representing a person associated with a Stripe account.</p><p>Related guide: <a href="https://stripe.com/docs/connect/identity-verification-api#person-information">Handling Identity Verification with the API</a>.</p>
  * @property \Stripe\StripeObject $metadata 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.
  * @property bool $payouts_enabled Whether Stripe can send payouts to this account.
  * @property \Stripe\StripeObject $requirements

lib/AccountLink.php

@@ -3,7 +3,13 @@
 namespace Stripe;
 
 /**
- * Class AccountLink.
+ * Account Links are the means by which a Connect platform grants a connected
+ * account permission to access Stripe-hosted applications, such as Connect
+ * Onboarding.
+ *
+ * Related guide: <a
+ * href="https://stripe.com/docs/connect/connect-onboarding">Connect
+ * Onboarding</a>.
  *
  * @property string $object String representing the object's type. Objects of the same type share the same value.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.

lib/ApplePayDomain.php

@@ -3,8 +3,6 @@
 namespace Stripe;
 
 /**
- * Class ApplePayDomain.
- *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.

lib/ApplicationFee.php

@@ -3,8 +3,6 @@
 namespace Stripe;
 
 /**
- * Class ApplicationFee.
- *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.
  * @property string|\Stripe\Account $account ID of the Stripe account this fee was taken from.

lib/Balance.php

@@ -3,10 +3,22 @@
 namespace Stripe;
 
 /**
- * Class Balance.
+ * This is an object representing your Stripe balance. You can retrieve it to see
+ * the balance currently on your Stripe account.
+ *
+ * You can also retrieve the balance history, which contains a list of <a
+ * href="https://stripe.com/docs/reporting/balance-transaction-types">transactions</a>
+ * that contributed to the balance (charges, payouts, and so forth).
+ *
+ * The available and pending amounts for each currency are broken down further by
+ * payment source types.
+ *
+ * Related guide: <a
+ * href="https://stripe.com/docs/connect/account-balances">Understanding Connect
+ * Account Balances</a>.
  *
  * @property string $object String representing the object's type. Objects of the same type share the same value.
- * @property \Stripe\StripeObject[] $available Funds that are available to be transferred or paid out, whether automatically by Stripe or explicitly via the <a href="#transfers">Transfers API</a> or <a href="#payouts">Payouts API</a>. The available balance for each currency and payment type can be found in the <code>source_types</code> property.
+ * @property \Stripe\StripeObject[] $available Funds that are available to be transferred or paid out, whether automatically by Stripe or explicitly via the <a href="https://stripe.com/docs/api#transfers">Transfers API</a> or <a href="https://stripe.com/docs/api#payouts">Payouts API</a>. The available balance for each currency and payment type can be found in the <code>source_types</code> property.
  * @property \Stripe\StripeObject[] $connect_reserved Funds held due to negative balances on connected Custom accounts. The connect reserve balance for each currency and payment type can be found in the <code>source_types</code> property.
  * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
  * @property \Stripe\StripeObject[] $pending Funds that are not yet available in the balance, due to the 7-day rolling pay cycle. The pending balance for each currency, and for each payment type, can be found in the <code>source_types</code> property.

lib/BalanceTransaction.php

@@ -3,7 +3,13 @@
 namespace Stripe;
 
 /**
- * Class BalanceTransaction.
+ * Balance transactions represent funds moving through your Stripe account. They're
+ * created for every type of transaction that comes into or flows out of your
+ * Stripe account balance.
+ *
+ * Related guide: <a
+ * href="https://stripe.com/docs/reports/balance-transaction-types">Balance
+ * Transaction Types</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/BankAccount.php

@@ -3,7 +3,18 @@
 namespace Stripe;
 
 /**
- * Class BankAccount.
+ * These bank accounts are payment methods on <code>Customer</code> objects.
+ *
+ * On the other hand <a
+ * href="https://stripe.com/docs/api#external_accounts">External Accounts</a> are
+ * transfer destinations on <code>Account</code> objects for <a
+ * href="https://stripe.com/docs/connect/custom-accounts">Custom accounts</a>. They
+ * can be bank accounts or debit cards as well, and are documented in the links
+ * above.
+ *
+ * Related guide: <a
+ * href="https://stripe.com/docs/payments/ach-bank-transfers">Processing ACH &amp;
+ * Bank Transfers</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/BitcoinReceiver.php

@@ -3,8 +3,6 @@
 namespace Stripe;
 
 /**
- * Class BitcoinReceiver.
- *
  * @deprecated Bitcoin receivers are deprecated. Please use the sources API instead.
  * @see https://stripe.com/docs/sources/bitcoin
  *

lib/Card.php

@@ -3,7 +3,12 @@
 namespace Stripe;
 
 /**
- * Class Card.
+ * You can store multiple cards on a customer in order to charge the customer
+ * later. You can also store multiple debit cards on a recipient in order to
+ * transfer to those cards later.
+ *
+ * Related guide: <a href="https://stripe.com/docs/sources/cards">Card Payments
+ * with Sources</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/Charge.php

@@ -3,7 +3,13 @@
 namespace Stripe;
 
 /**
- * Class Charge.
+ * To charge a credit or a debit card, you create a <code>Charge</code> object. You
+ * can retrieve and refund individual charges as well as list all charges. Charges
+ * are identified by a unique, random ID.
+ *
+ * Related guide: <a
+ * href="https://stripe.com/docs/payments/accept-a-payment-charges">Accept a
+ * payment with the Charges API</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/Checkout/Session.php

@@ -3,7 +3,22 @@
 namespace Stripe\Checkout;
 
 /**
- * Class Session.
+ * A Checkout Session represents your customer's session as they pay for one-time
+ * purchases or subscriptions through <a
+ * href="https://stripe.com/docs/payments/checkout">Checkout</a>. We recommend
+ * creating a new Session each time your customer attempts to pay.
+ *
+ * Once payment is successful, the Checkout Session will contain a reference to the
+ * <a href="https://stripe.com/docs/api/customers">Customer</a>, and either the
+ * successful <a
+ * href="https://stripe.com/docs/api/payment_intents">PaymentIntent</a> or an
+ * active <a href="https://stripe.com/docs/api/subscriptions">Subscription</a>.
+ *
+ * You can create a Checkout Session on your server and pass its ID to the client
+ * to begin Checkout.
+ *
+ * Related guide: <a href="https://stripe.com/docs/payments/checkout/api">Checkout
+ * Server Quickstart</a>.
  *
  * @property string $id Unique identifier for the object. Used to pass to <code>redirectToCheckout</code> in Stripe.js.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/CountrySpec.php

@@ -3,7 +3,12 @@
 namespace Stripe;
 
 /**
- * Class CountrySpec.
+ * Stripe needs to collect certain pieces of information about each account
+ * created. These requirements can differ depending on the account's country. The
+ * Country Specs API makes these rules available to your integration.
+ *
+ * You can also view the information from this API call as <a
+ * href="/docs/connect/required-verification-information">an online guide</a>.
  *
  * @property string $id Unique identifier for the object. Represented as the ISO country code for this country.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/Coupon.php

@@ -3,7 +3,12 @@
 namespace Stripe;
 
 /**
- * Class Coupon.
+ * A coupon contains information about a percent-off or amount-off discount you
+ * might want to apply to a customer. Coupons may be applied to <a
+ * href="https://stripe.com/docs/api#invoices">invoices</a> or <a
+ * href="https://stripe.com/docs/api#create_order-coupon">orders</a>. Coupons do
+ * not work with conventional one-off <a
+ * href="https://stripe.com/docs/api#create_charge">charges</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/CreditNote.php

@@ -3,7 +3,11 @@
 namespace Stripe;
 
 /**
- * Class CreditNote.
+ * Issue a credit note to adjust an invoice's amount after the invoice is
+ * finalized.
+ *
+ * Related guide: <a
+ * href="https://stripe.com/docs/billing/invoices/credit-notes">Credit Notes</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/Customer.php

@@ -3,7 +3,13 @@
 namespace Stripe;
 
 /**
- * Class Customer.
+ * <code>Customer</code> objects allow you to perform recurring charges, and to
+ * track multiple charges, that are associated with the same customer. The API
+ * allows you to create, delete, and update your customers. You can retrieve
+ * individual customers as well as a list of all your customers.
+ *
+ * Related guide: <a href="https://stripe.com/docs/saving-cards">Saving Cards with
+ * Customers</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/Dispute.php

@@ -3,7 +3,14 @@
 namespace Stripe;
 
 /**
- * Class Dispute.
+ * A dispute occurs when a customer questions your charge with their card issuer.
+ * When this happens, you're given the opportunity to respond to the dispute with
+ * evidence that shows that the charge is legitimate. You can find more information
+ * about the dispute process in our <a href="/docs/disputes">Disputes and Fraud</a>
+ * documentation.
+ *
+ * Related guide: <a href="https://stripe.com/docs/disputes">Disputes and
+ * Fraud</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/EphemeralKey.php

@@ -3,8 +3,6 @@
 namespace Stripe;
 
 /**
- * Class EphemeralKey.
- *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.

lib/Event.php

@@ -3,7 +3,39 @@
 namespace Stripe;
 
 /**
- * Class Event.
+ * Events are our way of letting you know when something interesting happens in
+ * your account. When an interesting event occurs, we create a new
+ * <code>Event</code> object. For example, when a charge succeeds, we create a
+ * <code>charge.succeeded</code> event; and when an invoice payment attempt fails,
+ * we create an <code>invoice.payment_failed</code> event. Note that many API
+ * requests may cause multiple events to be created. For example, if you create a
+ * new subscription for a customer, you will receive both a
+ * <code>customer.subscription.created</code> event and a
+ * <code>charge.succeeded</code> event.
+ *
+ * Events occur when the state of another API resource changes. The state of that
+ * resource at the time of the change is embedded in the event's data field. For
+ * example, a <code>charge.succeeded</code> event will contain a charge, and an
+ * <code>invoice.payment_failed</code> event will contain an invoice.
+ *
+ * As with other API resources, you can use endpoints to retrieve an <a
+ * href="https://stripe.com/docs/api#retrieve_event">individual event</a> or a <a
+ * href="https://stripe.com/docs/api#list_events">list of events</a> from the API.
+ * We also have a separate <a
+ * href="http://en.wikipedia.org/wiki/Webhook">webhooks</a> system for sending the
+ * <code>Event</code> objects directly to an endpoint on your server. Webhooks are
+ * managed in your <a href="https://dashboard.stripe.com/account/webhooks'">account
+ * settings</a>, and our <a href="https://stripe.com/docs/webhooks">Using
+ * Webhooks</a> guide will help you get set up.
+ *
+ * When using <a href="https://stripe.com/docs/connect">Connect</a>, you can also
+ * receive notifications of events that occur in connected accounts. For these
+ * events, there will be an additional <code>account</code> attribute in the
+ * received <code>Event</code> object.
+ *
+ * <strong>NOTE:</strong> Right now, access to events through the <a
+ * href="https://stripe.com/docs/api#retrieve_event">Retrieve Event API</a> is
+ * guaranteed only for 30 days.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/ExchangeRate.php

@@ -3,7 +3,17 @@
 namespace Stripe;
 
 /**
- * Class ExchangeRate.
+ * <code>Exchange Rate</code> objects allow you to determine the rates that Stripe
+ * is currently using to convert from one currency to another. Since this number is
+ * variable throughout the day, there are various reasons why you might want to
+ * know the current rate (for example, to dynamically price an item for a user with
+ * a default payment in a foreign currency).
+ *
+ * If you want a guarantee that the charge is made with a certain exchange rate you
+ * expect is current, you can pass in <code>exchange_rate</code> to charges
+ * endpoints. If the value is no longer up to date, the charge won't go through.
+ * Please refer to our <a href="https://stripe.com/docs/exchange-rates">Exchange
+ * Rates API</a> guide for more details.
  *
  * @property string $id Unique identifier for the object. Represented as the three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a> in lowercase.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/File.php

@@ -3,13 +3,21 @@
 namespace Stripe;
 
 /**
- * Class File.
+ * This is an object representing a file hosted on Stripe's servers. The file may
+ * have been uploaded by yourself using the <a
+ * href="https://stripe.com/docs/api#create_file">create file</a> request (for
+ * example, when uploading dispute evidence) or it may have been created by Stripe
+ * (for example, the results of a <a href="#scheduled_queries">Sigma scheduled
+ * query</a>).
+ *
+ * Related guide: <a href="https://stripe.com/docs/file-upload">File Upload
+ * Guide</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property null|string $filename A filename for the file, suitable for saving to a filesystem.
- * @property null|\Stripe\Collection $links A list of <a href="#file_links">file links</a> that point at this file.
+ * @property null|\Stripe\Collection $links A list of <a href="https://stripe.com/docs/api#file_links">file links</a> that point at this file.
  * @property string $purpose The purpose of the file. Possible values are <code>additional_verification</code>, <code>business_icon</code>, <code>business_logo</code>, <code>customer_signature</code>, <code>dispute_evidence</code>, <code>finance_report_run</code>, <code>identity_document</code>, <code>pci_document</code>, <code>sigma_scheduled_query</code>, or <code>tax_document_user_upload</code>.
  * @property int $size The size in bytes of the file object.
  * @property null|string $title A user friendly title for the document.

lib/FileLink.php

@@ -3,7 +3,9 @@
 namespace Stripe;
 
 /**
- * Class FileLink.
+ * To share the contents of a <code>File</code> object with non-Stripe users, you
+ * can create a <code>FileLink</code>. <code>FileLink</code>s contain a URL that
+ * can be used to retrieve the contents of the file without authentication.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/Invoice.php

@@ -3,7 +3,41 @@
 namespace Stripe;
 
 /**
- * Class Invoice.
+ * Invoices are statements of amounts owed by a customer, and are either generated
+ * one-off, or generated periodically from a subscription.
+ *
+ * They contain <a href="https://stripe.com/docs/api#invoiceitems">invoice
+ * items</a>, and proration adjustments that may be caused by subscription
+ * upgrades/downgrades (if necessary).
+ *
+ * If your invoice is configured to be billed through automatic charges, Stripe
+ * automatically finalizes your invoice and attempts payment. Note that finalizing
+ * the invoice, <a
+ * href="https://stripe.com/docs/billing/invoices/workflow/#auto_advance">when
+ * automatic</a>, does not happen immediately as the invoice is created. Stripe
+ * waits until one hour after the last webhook was successfully sent (or the last
+ * webhook timed out after failing). If you (and the platforms you may have
+ * connected to) have no webhooks configured, Stripe waits one hour after creation
+ * to finalize the invoice.
+ *
+ * If your invoice is configured to be billed by sending an email, then based on
+ * your <a href="https://dashboard.stripe.com/account/billing/automatic'">email
+ * settings</a>, Stripe will email the invoice to your customer and await payment.
+ * These emails can contain a link to a hosted page to pay the invoice.
+ *
+ * Stripe applies any customer credit on the account before determining the amount
+ * due for the invoice (i.e., the amount that will be actually charged). If the
+ * amount due for the invoice is less than Stripe's <a
+ * href="/docs/currencies#minimum-and-maximum-charge-amounts">minimum allowed
+ * charge per currency</a>, the invoice is automatically marked paid, and we add
+ * the amount due to the customer's running account balance which is applied to the
+ * next invoice.
+ *
+ * More details on the customer's account balance are <a
+ * href="https://stripe.com/docs/api/customers/object#customer_object-account_balance">here</a>.
+ *
+ * Related guide: <a href="https://stripe.com/docs/billing/invoices/sending">Send
+ * Invoices to Customers</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.