Improve docstrings for many properties and parameters

types/2019-12-03/Accounts.d.ts

@@ -261,7 +261,7 @@ declare module 'stripe' {
           line2: string | null;
 
           /**
-           * Zip/Postal Code.
+           * ZIP or postal code.
            */
           postal_code: string | null;
 
@@ -298,7 +298,7 @@ declare module 'stripe' {
           line2: string | null;
 
           /**
-           * Zip/Postal Code.
+           * ZIP or postal code.
            */
           postal_code: string | null;
 
@@ -802,6 +802,9 @@ declare module 'stripe' {
          */
         dob?: Individual.Dob | null;
 
+        /**
+         * The individual's email address.
+         */
         email?: string;
 
         /**
@@ -1394,6 +1397,9 @@ declare module 'stripe' {
          */
         dob?: Individual.Dob | null;
 
+        /**
+         * The individual's email address.
+         */
         email?: string;
 
         /**

types/2019-12-03/AlipayAccounts.d.ts

@@ -19,6 +19,9 @@ declare module 'stripe' {
        */
       created: number;
 
+      /**
+       * The ID of the customer associated with this Alipay Account.
+       */
       customer?: string | Stripe.Customer | Stripe.DeletedCustomer | null;
 
       deleted?: void;

types/2019-12-03/BalanceTransactions.d.ts

@@ -39,6 +39,9 @@ declare module 'stripe' {
        */
       description: string | null;
 
+      /**
+       * The exchange rate used, if applicable, for this transaction. Specifically, if money was converted from currency A to currency B, then the `amount` in currency A, times `exchange_rate`, would be the `amount` in currency B. For example, suppose you charged a customer 10.00 EUR. Then the PaymentIntent's `amount` would be `1000` and `currency` would be `eur`. Suppose this was converted into 12.34 USD in your Stripe account. Then the BalanceTransaction's `amount` would be `1234`, `currency` would be `usd`, and `exchange_rate` would be `1.234`.
+       */
       exchange_rate: number | null;
 
       /**
@@ -101,6 +104,9 @@ declare module 'stripe' {
          */
         amount: number;
 
+        /**
+         * ID of the Connect application that earned the fee.
+         */
         application: string | null;
 
         /**
@@ -163,6 +169,9 @@ declare module 'stripe' {
 
       created?: RangeQueryParam | number;
 
+      /**
+       * Only return transactions in a certain currency. Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
+       */
       currency?: string;
 
       /**

types/2019-12-03/BankAccounts.d.ts

@@ -14,6 +14,9 @@ declare module 'stripe' {
        */
       object: 'bank_account';
 
+      /**
+       * The ID of the account that the bank account is associated with.
+       */
       account?: string | Stripe.Account | null;
 
       /**
@@ -41,6 +44,9 @@ declare module 'stripe' {
        */
       currency: string;
 
+      /**
+       * The ID of the customer that the bank account is associated with.
+       */
       customer?: string | Stripe.Customer | Stripe.DeletedCustomer | null;
 
       /**
@@ -55,6 +61,9 @@ declare module 'stripe' {
        */
       fingerprint: string | null;
 
+      /**
+       * The last four digits of the bank account number.
+       */
       last4: string;
 
       /**

types/2019-12-03/BitcoinReceivers.d.ts

@@ -54,6 +54,9 @@ declare module 'stripe' {
        */
       currency: string;
 
+      /**
+       * The customer ID of the bitcoin receiver.
+       */
       customer?: string | null;
 
       deleted?: void;
@@ -93,6 +96,9 @@ declare module 'stripe' {
        */
       payment?: string | null;
 
+      /**
+       * The refund address of this bitcoin receiver.
+       */
       refund_address: string | null;
 
       /**
@@ -105,6 +111,9 @@ declare module 'stripe' {
        */
       uncaptured_funds: boolean;
 
+      /**
+       * Indicate if this source is used for payment.
+       */
       used_for_payment: boolean | null;
     }
 

types/2019-12-03/Charges.d.ts

@@ -1339,6 +1339,9 @@ declare module 'stripe' {
 
     namespace ChargeUpdateParams {
       interface FraudDetails {
+        /**
+         * Either `safe` or `fraudulent`.
+         */
         user_report: FraudDetails.UserReport | null;
       }
 

types/2019-12-03/CreditNotes.d.ts

@@ -45,7 +45,7 @@ declare module 'stripe' {
       /**
        * The integer amount in **%s** representing the amount of the discount that was credited.
        */
-      discount_amount?: number;
+      discount_amount: number;
 
       /**
        * ID of the invoice.
@@ -55,7 +55,7 @@ declare module 'stripe' {
       /**
        * Line items that make up the credit note
        */
-      lines?: ApiList<Stripe.CreditNoteLineItem>;
+      lines: ApiList<Stripe.CreditNoteLineItem>;
 
       /**
        * Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
@@ -80,7 +80,7 @@ declare module 'stripe' {
       /**
        * Amount that was credited outside of Stripe.
        */
-      out_of_band_amount?: number | null;
+      out_of_band_amount: number | null;
 
       /**
        * The link to download the PDF of the credit note.
@@ -105,17 +105,17 @@ declare module 'stripe' {
       /**
        * The integer amount in **%s** representing the amount of the credit note, excluding tax and discount.
        */
-      subtotal?: number;
+      subtotal: number;
 
       /**
        * The aggregate amounts calculated per tax rate for all line items.
        */
-      tax_amounts?: Array<CreditNote.TaxAmount>;
+      tax_amounts: Array<CreditNote.TaxAmount>;
 
       /**
        * The integer amount in **%s** representing the total amount of the credit note, including tax and discount.
        */
-      total?: number;
+      total: number;
 
       /**
        * Type of this credit note, one of `post_payment` or `pre_payment`. A `pre_payment` credit note means it was issued when the invoice was open. A `post_payment` credit note means it was issued when the invoice was paid.

types/2019-12-03/CustomerSources.d.ts

@@ -120,16 +120,34 @@ declare module 'stripe' {
 
       namespace Owner {
         interface Address {
+          /**
+           * City, district, suburb, town, or village.
+           */
           city?: string;
 
+          /**
+           * Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
+           */
           country?: string;
 
+          /**
+           * Address line 1 (e.g., street, PO Box, or company name).
+           */
           line1?: string;
 
+          /**
+           * Address line 2 (e.g., apartment, suite, unit, or building).
+           */
           line2?: string;
 
+          /**
+           * ZIP or postal code.
+           */
           postal_code?: string;
 
+          /**
+           * State, county, province, or region.
+           */
           state?: string;
         }
       }

types/2019-12-03/Discounts.d.ts

@@ -11,6 +11,9 @@ declare module 'stripe' {
 
       coupon: Stripe.Coupon;
 
+      /**
+       * The ID of the customer associated with this discount.
+       */
       customer: string | Stripe.Customer | Stripe.DeletedCustomer | null;
 
       deleted?: void;

types/2019-12-03/Disputes.d.ts

@@ -282,80 +282,137 @@ declare module 'stripe' {
     namespace DisputeUpdateParams {
       interface Evidence {
         /**
-         * Has a maximum character count of 20,000.
+         * Any server or activity logs showing proof that the customer accessed or downloaded the purchased digital product. This information should include IP addresses, corresponding timestamps, and any detailed recorded activity. Has a maximum character count of 20,000.
          */
         access_activity_log?: string;
 
+        /**
+         * The billing address provided by the customer.
+         */
         billing_address?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) Your subscription cancellation policy, as shown to the customer.
+         */
         cancellation_policy?: string;
 
         /**
-         * Has a maximum character count of 20,000.
+         * An explanation of how and when the customer was shown your refund policy prior to purchase. Has a maximum character count of 20,000.
          */
         cancellation_policy_disclosure?: string;
 
         /**
-         * Has a maximum character count of 20,000.
+         * A justification for why the customer's subscription was not canceled. Has a maximum character count of 20,000.
          */
         cancellation_rebuttal?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) Any communication with the customer that you feel is relevant to your case. Examples include emails proving that the customer received the product or service, or demonstrating their use of or satisfaction with the product or service.
+         */
         customer_communication?: string;
 
+        /**
+         * The email address of the customer.
+         */
         customer_email_address?: string;
 
+        /**
+         * The name of the customer.
+         */
         customer_name?: string;
 
+        /**
+         * The IP address that the customer used when making the purchase.
+         */
         customer_purchase_ip?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) A relevant document or contract showing the customer's signature.
+         */
         customer_signature?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) Documentation for the prior charge that can uniquely identify the charge, such as a receipt, shipping label, work order, etc. This document should be paired with a similar document from the disputed payment that proves the two payments are separate.
+         */
         duplicate_charge_documentation?: string;
 
         /**
-         * Has a maximum character count of 20,000.
+         * An explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate. Has a maximum character count of 20,000.
          */
         duplicate_charge_explanation?: string;
 
+        /**
+         * The Stripe ID for the prior charge which appears to be a duplicate of the disputed charge.
+         */
         duplicate_charge_id?: string;
 
         /**
-         * Has a maximum character count of 20,000.
+         * A description of the product or service that was sold. Has a maximum character count of 20,000.
          */
         product_description?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) Any receipt or message sent to the customer notifying them of the charge.
+         */
         receipt?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) Your refund policy, as shown to the customer.
+         */
         refund_policy?: string;
 
         /**
-         * Has a maximum character count of 20,000.
+         * Documentation demonstrating that the customer was shown your refund policy prior to purchase. Has a maximum character count of 20,000.
          */
         refund_policy_disclosure?: string;
 
         /**
-         * Has a maximum character count of 20,000.
+         * A justification for why the customer is not entitled to a refund. Has a maximum character count of 20,000.
          */
         refund_refusal_explanation?: string;
 
+        /**
+         * The date on which the customer received or began receiving the purchased service, in a clear human-readable format.
+         */
         service_date?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) Documentation showing proof that a service was provided to the customer. This could include a copy of a signed contract, work order, or other form of written agreement.
+         */
         service_documentation?: string;
 
+        /**
+         * The address to which a physical product was shipped. You should try to include as complete address information as possible.
+         */
         shipping_address?: string;
 
+        /**
+         * The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas.
+         */
         shipping_carrier?: string;
 
+        /**
+         * The date on which a physical product began its route to the shipping address, in a clear human-readable format.
+         */
         shipping_date?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) Documentation showing proof that a product was shipped to the customer at the same address the customer provided to you. This could include a copy of the shipment receipt, shipping label, etc. It should show the customer's full shipping address, if possible.
+         */
         shipping_documentation?: string;
 
+        /**
+         * The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.
+         */
         shipping_tracking_number?: string;
 
+        /**
+         * (ID of a [file upload](https://stripe.com/docs/guides/file-upload)) Any additional evidence or statements.
+         */
         uncategorized_file?: string;
 
         /**
-         * Has a maximum character count of 20,000.
+         * Any additional evidence or statements. Has a maximum character count of 20,000.
          */
         uncategorized_text?: string;
       }

types/2019-12-03/Files.d.ts

@@ -24,6 +24,9 @@ declare module 'stripe' {
        */
       filename: string | null;
 
+      /**
+       * A list of [file links](https://stripe.com/docs/api#file_links) that point at this file.
+       */
       links?: ApiList<Stripe.FileLink> | null;
 
       /**