Merge pull request #902 from stripe/richardm-autogenned-nestedresourc…

…e-docstrings

Update docstrings for nested resources

lib/ApplicationFeeRefund.php

@@ -3,16 +3,22 @@
 namespace Stripe;
 
 /**
- * Class ApplicationFeeRefund.
+ * <code>Application Fee Refund</code> objects allow you to refund an application
+ * fee that has previously been created but not yet refunded. Funds will be
+ * refunded to the Stripe account from which the fee was originally collected.
  *
- * @property string $id
- * @property string $object
- * @property int $amount
- * @property string $balance_transaction
- * @property int $created
- * @property string $currency
- * @property string $fee
- * @property \Stripe\StripeObject $metadata
+ * Related guide: <a
+ * href="https://stripe.com/docs/connect/destination-charges#refunding-app-fee">Refunding
+ * Application Fees</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 $amount Amount, in %s.
+ * @property null|string|\Stripe\BalanceTransaction $balance_transaction Balance transaction that describes the impact on your account balance.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
+ * @property string $currency Three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a>, in lowercase. Must be a <a href="https://stripe.com/docs/currencies">supported currency</a>.
+ * @property string|\Stripe\ApplicationFee $fee ID of the application fee that was refunded.
+ * @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.
  */
 class ApplicationFeeRefund extends ApiResource
 {

lib/BitcoinTransaction.php

@@ -3,7 +3,13 @@
 namespace Stripe;
 
 /**
- * Class BitcoinTransaction.
+ * @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 $amount The amount of <code>currency</code> that the transaction was converted to in real-time.
+ * @property int $bitcoin_amount The amount of bitcoin contained in the transaction.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
+ * @property string $currency Three-letter <a href="https://stripe.com/docs/currencies">ISO code for the currency</a> to which this transaction was converted.
+ * @property string $receiver The receiver to which this transaction was sent.
  */
 class BitcoinTransaction extends ApiResource
 {

lib/Capability.php

@@ -3,15 +3,19 @@
 namespace Stripe;
 
 /**
- * Class Capability.
+ * This is an object representing a capability for a Stripe account.
  *
- * @property string $id
- * @property string $object
- * @property string $account
- * @property bool $requested
- * @property int $requested_at
+ * Related guide: <a
+ * href="https://stripe.com/docs/connect/capabilities-overview">Capabilities
+ * Overview</a>.
+ *
+ * @property string $id The identifier for the capability.
+ * @property string $object String representing the object's type. Objects of the same type share the same value.
+ * @property string|\Stripe\Account $account The account for which the capability enables functionality.
+ * @property bool $requested Whether the capability has been requested.
+ * @property null|int $requested_at Time at which the capability was requested. Measured in seconds since the Unix epoch.
  * @property \Stripe\StripeObject $requirements
- * @property string $status
+ * @property string $status The status of the capability. Can be <code>active</code>, <code>inactive</code>, <code>pending</code>, or <code>unrequested</code>.
  */
 class Capability extends ApiResource
 {

lib/CustomerBalanceTransaction.php

@@ -3,21 +3,31 @@
 namespace Stripe;
 
 /**
- * Class CustomerBalanceTransaction.
+ * Each customer has a <a
+ * href="https://stripe.com/docs/api/customers/object#customer_object-balance"><code>balance</code></a>
+ * value, which denotes a debit or credit that's automatically applied to their
+ * next invoice upon finalization. You may modify the value directly by using the
+ * <a href="https://stripe.com/docs/api/customers/update">update customer API</a>,
+ * or by creating a Customer Balance Transaction, which increments or decrements
+ * the customer's <code>balance</code> by the specified <code>amount</code>.
  *
- * @property string $id
- * @property string $object
- * @property int $amount
- * @property string $credit_note
- * @property int $created
- * @property string $currency
- * @property string $customer
- * @property string $description
- * @property int $ending_balance
- * @property string $invoice
- * @property bool $livemode
- * @property \Stripe\StripeObject $metadata
- * @property string $type
+ * Related guide: <a
+ * href="https://stripe.com/docs/billing/customer/balance">Customer Balance</a> to
+ * learn more.
+ *
+ * @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 $amount The amount of the transaction. A negative value is a credit for the customer's balance, and a positive value is a debit to the customer's <code>balance</code>.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
+ * @property null|string|\Stripe\CreditNote $credit_note The ID of the credit note (if any) related to the transaction.
+ * @property string $currency Three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a>, in lowercase. Must be a <a href="https://stripe.com/docs/currencies">supported currency</a>.
+ * @property string|\Stripe\Customer $customer The ID of the customer the transaction belongs to.
+ * @property null|string $description An arbitrary string attached to the object. Often useful for displaying to users.
+ * @property int $ending_balance The customer's <code>balance</code> after the transaction was applied. A negative value decreases the amount due on the customer's next invoice. A positive value increases the amount due on the customer's next invoice.
+ * @property null|string|\Stripe\Invoice $invoice The ID of the invoice (if any) related to the transaction.
+ * @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 null|\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 string $type Transaction type: <code>adjustment</code>, <code>applied_to_invoice</code>, <code>credit_note</code>, <code>initial</code>, <code>invoice_too_large</code>, <code>invoice_too_small</code>, <code>unspent_receiver_credit</code>, or <code>unapplied_from_invoice</code>. See the <a href="https://stripe.com/docs/billing/customer/balance#types">Customer Balance page</a> to learn more about transaction types.
  */
 class CustomerBalanceTransaction extends ApiResource
 {

lib/InvoiceLineItem.php

@@ -3,26 +3,25 @@
 namespace Stripe;
 
 /**
- * Class InvoiceLineItem.
- *
- * @property string $id
- * @property string $object
- * @property int $amount
- * @property string $currency
- * @property string $description
- * @property bool $discountable
- * @property string $invoice_item
- * @property bool $livemode
- * @property \Stripe\StripeObject $metadata
+ * @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 $amount The amount, in %s.
+ * @property string $currency Three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a>, in lowercase. Must be a <a href="https://stripe.com/docs/currencies">supported currency</a>.
+ * @property null|string $description An arbitrary string attached to the object. Often useful for displaying to users.
+ * @property bool $discountable If true, discounts will apply to this line item. Always false for prorations.
+ * @property string $invoice_item The ID of the <a href="https://stripe.com/docs/api/invoiceitems">invoice item</a> associated with this line item if any.
+ * @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 $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. Note that for line items with <code>type=subscription</code> this will reflect the metadata of the subscription that caused the line item to be created.
  * @property \Stripe\StripeObject $period
- * @property \Stripe\Plan $plan
- * @property bool $proration
- * @property int $quantity
- * @property string $subscription
- * @property string $subscription_item
- * @property array $tax_amounts
- * @property array $tax_rates
- * @property string $type
+ * @property null|\Stripe\Plan $plan The plan of the subscription, if the line item is a subscription or a proration.
+ * @property bool $proration Whether this is a proration.
+ * @property null|int $quantity The quantity of the subscription, if the line item is a subscription or a proration.
+ * @property null|string $subscription The subscription that the invoice item pertains to, if any.
+ * @property string $subscription_item The subscription item that generated this invoice item. Left empty if the line item is not an explicit result of a subscription.
+ * @property null|\Stripe\StripeObject[] $tax_amounts The amount of tax calculated per tax rate for this line item
+ * @property null|\Stripe\TaxRate[] $tax_rates The tax rates which apply to the line item.
+ * @property string $type A string identifying the type of the source of this line item, either an <code>invoiceitem</code> or a <code>subscription</code>.
+ * @property bool $unified_proration For prorations this indicates whether Stripe automatically grouped multiple related debit and credit line items into a single combined line item.
  */
 class InvoiceLineItem extends ApiResource
 {

lib/LoginLink.php

@@ -3,11 +3,9 @@
 namespace Stripe;
 
 /**
- * Class LoginLink.
- *
- * @property string $object
- * @property int $created
- * @property string $url
+ * @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 string $url The URL for the login link.
  */
 class LoginLink extends ApiResource
 {

lib/Person.php

@@ -3,32 +3,35 @@
 namespace Stripe;
 
 /**
- * Class Person.
+ * This is an object representing a person associated with a Stripe account.
  *
- * @property string $id
- * @property string $object
- * @property string $account
+ * Related guide: <a
+ * href="https://stripe.com/docs/connect/identity-verification-api#person-information">Handling
+ * Identity Verification with the 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.
+ * @property string $account The account the person is associated with.
  * @property \Stripe\StripeObject $address
- * @property null|\Stripe\StripeObject $address_kana
- * @property null|\Stripe\StripeObject $address_kanji
- * @property int $created
- * @property bool $deleted
+ * @property null|\Stripe\StripeObject $address_kana The Kana variation of the person's address (Japan only).
+ * @property null|\Stripe\StripeObject $address_kanji The Kanji variation of the person's address (Japan only).
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property \Stripe\StripeObject $dob
- * @property null|string $email
- * @property null|string $first_name
- * @property null|string $first_name_kana
- * @property null|string $first_name_kanji
- * @property null|string $gender
- * @property bool $id_number_provided
- * @property null|string $last_name
- * @property null|string $last_name_kana
- * @property null|string $last_name_kanji
- * @property null|string $maiden_name
- * @property \Stripe\StripeObject $metadata
- * @property null|string $phone
+ * @property null|string $email The person's email address.
+ * @property null|string $first_name The person's first name.
+ * @property null|string $first_name_kana The Kana variation of the person's first name (Japan only).
+ * @property null|string $first_name_kanji The Kanji variation of the person's first name (Japan only).
+ * @property null|string $gender The person's gender (International regulations require either &quot;male&quot; or &quot;female&quot;).
+ * @property bool $id_number_provided Whether the person's <code>id_number</code> was provided.
+ * @property null|string $last_name The person's last name.
+ * @property null|string $last_name_kana The Kana variation of the person's last name (Japan only).
+ * @property null|string $last_name_kanji The Kanji variation of the person's last name (Japan only).
+ * @property null|string $maiden_name The person's maiden name.
+ * @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 null|string $phone The person's phone number.
  * @property \Stripe\StripeObject $relationship
- * @property null|\Stripe\StripeObject $requirements
- * @property bool $ssn_last_4_provided
+ * @property null|\Stripe\StripeObject $requirements Information about the requirements for this person, including what information needs to be collected, and by when.
+ * @property bool $ssn_last_4_provided Whether the last 4 digits of this person's SSN have been provided.
  * @property \Stripe\StripeObject $verification
  */
 class Person extends ApiResource

lib/TaxId.php

@@ -3,16 +3,21 @@
 namespace Stripe;
 
 /**
- * Class TaxId.
+ * You can add one or multiple tax IDs to a <a
+ * href="https://stripe.com/docs/api/customers">customer</a>. A customer's tax IDs
+ * are displayed on invoices and credit notes issued for the customer.
  *
- * @property string $id
- * @property string $object
- * @property string $country
- * @property int $created
- * @property string $customer
- * @property bool $livemode
- * @property string $type
- * @property string $value
+ * Related guide: <a href="https://stripe.com/docs/billing/taxes/tax-ids">Customer
+ * Tax Identification Numbers</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 null|string $country Two-letter ISO code representing the country of the tax ID.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
+ * @property string|\Stripe\Customer $customer ID of the customer.
+ * @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 string $type Type of the tax ID, one of <code>au_abn</code>, <code>ca_bn</code>, <code>ca_qst</code>, <code>ch_vat</code>, <code>es_cif</code>, <code>eu_vat</code>, <code>hk_br</code>, <code>in_gst</code>, <code>jp_cn</code>, <code>kr_brn</code>, <code>li_uid</code>, <code>mx_rfc</code>, <code>my_itn</code>, <code>my_sst</code>, <code>no_vat</code>, <code>nz_gst</code>, <code>ru_inn</code>, <code>sg_uen</code>, <code>th_vat</code>, <code>tw_vat</code>, <code>us_ein</code>, or <code>za_vat</code>. Note that some legacy tax IDs have type <code>unknown</code>
+ * @property string $value Value of the tax ID.
  * @property \Stripe\StripeObject $verification
  */
 class TaxId extends ApiResource

lib/TransferReversal.php

@@ -3,18 +3,33 @@
 namespace Stripe;
 
 /**
- * Class TransferReversal.
+ * <a href="https://stripe.com/docs/connect">Stripe Connect</a> platforms can
+ * reverse transfers made to a connected account, either entirely or partially, and
+ * can also specify whether to refund any related application fees. Transfer
+ * reversals add to the platform's balance and subtract from the destination
+ * account's balance.
  *
- * @property string $id
- * @property string $object
- * @property int $amount
- * @property string $balance_transaction
- * @property int $created
- * @property string $currency
- * @property string $destination_payment_refund
- * @property \Stripe\StripeObject $metadata
- * @property string $source_refund
- * @property string $transfer
+ * Reversing a transfer that was made for a <a
+ * href="/docs/connect/destination-charges">destination charge</a> is allowed only
+ * up to the amount of the charge. It is possible to reverse a <a
+ * href="https://stripe.com/docs/connect/charges-transfers#transfer-options">transfer_group</a>
+ * transfer only if the destination account has enough balance to cover the
+ * reversal.
+ *
+ * Related guide: <a
+ * href="https://stripe.com/docs/connect/charges-transfers#reversing-transfers">Reversing
+ * 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.
+ * @property int $amount Amount, in %s.
+ * @property null|string|\Stripe\BalanceTransaction $balance_transaction Balance transaction that describes the impact on your account balance.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
+ * @property string $currency Three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a>, in lowercase. Must be a <a href="https://stripe.com/docs/currencies">supported currency</a>.
+ * @property null|string|\Stripe\Refund $destination_payment_refund Linked payment refund for the transfer reversal.
+ * @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 null|string|\Stripe\Refund $source_refund ID of the refund responsible for the transfer reversal.
+ * @property string|\Stripe\Transfer $transfer ID of the transfer that was reversed.
  */
 class TransferReversal extends ApiResource
 {

lib/UsageRecord.php

@@ -3,14 +3,19 @@
 namespace Stripe;
 
 /**
- * Class UsageRecord.
+ * Usage records allow you to report customer usage and metrics to Stripe for
+ * metered billing of subscription plans.
  *
- * @property string $id
- * @property string $object
- * @property bool $livemode
- * @property int $quantity
- * @property string $subscription_item
- * @property int $timestamp
+ * Related guide: <a
+ * href="https://stripe.com/docs/billing/subscriptions/metered-billing">Metered
+ * Billing</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 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 int $quantity The usage quantity for the specified date.
+ * @property string $subscription_item The ID of the subscription item this usage record contains data for.
+ * @property int $timestamp The timestamp when this usage occurred.
  */
 class UsageRecord extends ApiResource
 {