undeprecate STPBackendAPIAdapter and update documentation

Stripe/PublicHeaders/STPBackendAPIAdapter.h

@@ -19,20 +19,17 @@ NS_ASSUME_NONNULL_BEGIN
 @class STPCard, STPToken;
 
 /**
- Note: Instead of providing your own backend API adapter, you can now create an
- `STPCustomerContext`, which conforms to this protocol, and will manage retrieving 
- and updating a Stripe customer for you. @see STPCustomerContext.h
+ Typically, you will not need to implement this protocol yourself. You
+ should instead use `STPCustomerContext`, which implements <STPBackendAPIAdapter>
+ and manages retrieving and updating a Stripe customer for you.
+ @see STPCustomerContext.h
 
  If you would prefer retrieving and updating your Stripe customer object via
  your own backend instead of using `STPCustomerContext`, you should make your 
  application's API client conform to this interface. It provides a "bridge" from 
  the prebuilt UI we expose (such as `STPPaymentMethodsViewController`) to your
  backend to fetch the information it needs to power those views.
-
- @deprecated Use `STPCustomerContext`.
-
  */
-__attribute__((deprecated))
 @protocol STPBackendAPIAdapter<NSObject>
 
 /**
@@ -53,7 +50,7 @@ __attribute__((deprecated))
 /**
  Adds a payment source to a customer. 
 
- If you are not using STPCustomerContext:
+ If you are implementing your own <STPBackendAPIAdapter>:
  On your backend, retrieve the Stripe customer associated with your logged-in user. 
  Then, call the Update Customer method on that customer
  ( https://stripe.com/docs/api#update_customer ). If this API call succeeds,
@@ -70,8 +67,8 @@ __attribute__((deprecated))
 /**
  Change a customer's `default_source` to be the provided card. 
 
- If you are not using STPCustomerContext:
- On your backend, retrieve the Stripe customer associated with your logged-in user. 
+ If you are implementing your own <STPBackendAPIAdapter>:
+ On your backend, retrieve the Stripe customer associated with your logged-in user.
  Then, call the Customer Update method ( https://stripe.com/docs/api#update_customer )
  specifying default_source to be the value of source.stripeID. If this API call 
  succeeds, call `completion(nil)`. Otherwise, call `completion(error)` with the 
@@ -88,18 +85,29 @@ __attribute__((deprecated))
 
 /**
  Deletes the given source from the customer.
+ 
+ If you are implementing your own <STPBackendAPIAdapter>:
+ On your backend, retrieve the Stripe customer associated with your logged-in user.
+ Then, call the Delete Card method ( https://stripe.com/docs/api#delete_card )
+ specifying id to be the value of source.stripeID. If this API call
+ succeeds, call `completion(nil)`. Otherwise, call `completion(error)` with the
+ error that occurred.
 
  @param source    The source to delete from the customer
  @param completion call this callback when you're done deleting the source from
  the customer on your backend. For example, `completion(nil)` (if your call
  succeeds) or `completion(error)` if an error is returned.
-
- @see https://stripe.com/docs/api#delete_card
  */
 - (void)detachSourceFromCustomer:(id<STPSourceProtocol>)source completion:(nullable STPErrorBlock)completion;
 
 /**
  Sets the given shipping address on the customer.
+ 
+ If you are implementing your own <STPBackendAPIAdapter>:
+ On your backend, retrieve the Stripe customer associated with your logged-in user.
+ Then, call the Customer Update method ( https://stripe.com/docs/api#update_customer )
+ specifying shipping to be the given shipping address. If this API call succeeds, 
+ call `completion(nil)`. Otherwise, call `completion(error)` with the error that occurred.
 
  @param shipping   The shipping address to set on the customer
  @param completion call this callback when you're done updating the customer on

Stripe/PublicHeaders/STPCustomer.h

@@ -29,13 +29,10 @@ NS_ASSUME_NONNULL_BEGIN
  @param sources       All of the customer's payment sources. This might be an empty array.
 
  @return an instance of STPCustomer
-
- @deprecated Use `STPCustomerContext` to manage retrieving and updating a 
- Customer. You will no longer need to initialize an `STPCustomer`.
  */
 + (instancetype)customerWithStripeID:(NSString *)stripeID
                        defaultSource:(nullable id<STPSourceProtocol>)defaultSource
-                             sources:(NSArray<id<STPSourceProtocol>> *)sources __attribute__((deprecated));
+                             sources:(NSArray<id<STPSourceProtocol>> *)sources;
 
 /**
  The Stripe ID of the customer, e.g. `cus_1234`
@@ -65,28 +62,30 @@ NS_ASSUME_NONNULL_BEGIN
 @interface STPCustomerDeserializer : NSObject
 
 /**
- Initialize a customer deserializer. The `data`, `urlResponse`, and `error` parameters are intended to be passed from an `NSURLSessionDataTask` callback. After it has been initialized, you can inspect the `error` and `customer` properties to see if the deserialization was successful. If `error` is nil, `customer` will be non-nil (and vice versa).
+ Initialize a customer deserializer. The `data`, `urlResponse`, and `error` 
+ parameters are intended to be passed from an `NSURLSessionDataTask` callback. 
+ After it has been initialized, you can inspect the `error` and `customer` 
+ properties to see if the deserialization was successful. If `error` is nil, 
+ `customer` will be non-nil (and vice versa).
 
  @param data        An `NSData` object representing encoded JSON for a Customer object
  @param urlResponse The URL response obtained from the `NSURLSessionTask`
- @param error       Any error that occurred from the URL session task (if this is non-nil, the `error` property will be set to this value after initialization).
-
- @deprecated Use `STPCustomerContext` to manage retrieving and updating a
- Customer. You will no longer need to deserialize an `STPCustomer`.
+ @param error       Any error that occurred from the URL session task (if this 
+ is non-nil, the `error` property will be set to this value after initialization).
  */
 - (instancetype)initWithData:(nullable NSData *)data
                  urlResponse:(nullable NSURLResponse *)urlResponse
-                       error:(nullable NSError *)error __attribute__((deprecated));
+                       error:(nullable NSError *)error;
 
 /**
- Initializes a customer deserializer with a JSON dictionary. This JSON should be in the exact same format as what the Stripe API returns. If it's successfully parsed, the `customer` parameter will be present after initialization; otherwise `error` will be present.
+ Initializes a customer deserializer with a JSON dictionary. This JSON should be 
+ in the exact same format as what the Stripe API returns. If it's successfully 
+ parsed, the `customer` parameter will be present after initialization; 
+ otherwise `error` will be present.
 
  @param json a JSON dictionary.
-
- @deprecated Use `STPCustomerContext` to manage retrieving and updating a
- Customer. You will no longer need to deserialize an `STPCustomer`.
  */
-- (instancetype)initWithJSONResponse:(id)json __attribute__((deprecated));
+- (instancetype)initWithJSONResponse:(id)json;
 
 /**
  If a customer was successfully parsed from the response, it will be set here. Otherwise, this value wil be nil (and the `error` property will explain what went wrong).

Stripe/PublicHeaders/STPCustomerContext.h

@@ -15,8 +15,6 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol STPEphemeralKeyProvider;
 @class STPEphemeralKey, STPEphemeralKeyManager;
 
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 /**
  An `STPCustomerContext` retrieves and updates a Stripe customer using
  an ephemeral key, a short-lived API key scoped to a specific customer object.
@@ -26,7 +24,6 @@ NS_ASSUME_NONNULL_BEGIN
  new ephemeral key for the Customer object associated with the new user.
  */
 @interface STPCustomerContext : NSObject <STPBackendAPIAdapter>
-#pragma clang diagnostic pop
 
 /**
  Initializes a new `STPCustomerContext` with the specified key provider.

Stripe/PublicHeaders/STPPaymentContext.h

@@ -50,51 +50,61 @@ NS_ASSUME_NONNULL_BEGIN
 
  @param customerContext   The customer context the payment context will use to fetch
  and modify its Stripe customer. @see STPCustomerContext.h
- @param configuration     The configuration for the payment context to use. This lets you set your Stripe publishable API key, required billing address fields, etc. @see STPPaymentConfiguration.h
- @param theme             The theme describing the visual appearance of all UI that the payment context automatically creates for you. @see STPTheme.h
+ @param configuration     The configuration for the payment context to use. This 
+ lets you set your Stripe publishable API key, required billing address fields, etc. 
+ @see STPPaymentConfiguration.h
+ @param theme             The theme describing the visual appearance of all UI 
+ that the payment context automatically creates for you. @see STPTheme.h
  @return the newly-instantiated payment context
  */
 - (instancetype)initWithCustomerContext:(STPCustomerContext *)customerContext
                           configuration:(STPPaymentConfiguration *)configuration
                                   theme:(STPTheme *)theme;
 
 /**
- This is a convenience initializer; it is equivalent to calling `initWithAPIAdapter:apiAdapter configuration:[STPPaymentConfiguration sharedConfiguration] theme:[STPTheme defaultTheme]`.
-
- @deprecated Use `initWithCustomerContext:`.
- Instead of providing your own backend API adapter, you can now create an
+ Note: Instead of providing your own backend API adapter, we recommend using
  `STPCustomerContext`, which will manage retrieving and updating a
  Stripe customer for you. @see STPCustomerContext.h
+
+ This is a convenience initializer; it is equivalent to calling 
+ `initWithAPIAdapter:apiAdapter configuration:[STPPaymentConfiguration sharedConfiguration] theme:[STPTheme defaultTheme]`.
  */
-- (instancetype)initWithAPIAdapter:(id<STPBackendAPIAdapter>)apiAdapter __attribute__((deprecated));
+- (instancetype)initWithAPIAdapter:(id<STPBackendAPIAdapter>)apiAdapter;
 
 /**
- Initializes a new Payment Context with the provided API adapter and configuration. After this class is initialized, you should also make sure to set its `delegate` and `hostViewController` properties.
-
- @param apiAdapter    The API adapter the payment context will use to fetch and modify its contents. You need to make a class conforming to this protocol that talks to your server. @see STPBackendAPIAdapter.h
- @param configuration The configuration for the payment context to use. This lets you set your Stripe publishable API key, required billing address fields, etc. @see STPPaymentConfiguration.h
- @param theme         The theme describing the visual appearance of all UI that the payment context automatically creates for you. @see STPTheme.h
-
- @return the newly-instantiated payment context
-
- @deprecated Use `initWithCustomerContext:configuration:theme:`.
- Instead of providing your own backend API adapter, you can now create an
+ Note: Instead of providing your own backend API adapter, we recommend using
  `STPCustomerContext`, which will manage retrieving and updating a
  Stripe customer for you. @see STPCustomerContext.h
+ 
+ Initializes a new Payment Context with the provided API adapter and configuration. 
+ After this class is initialized, you should also make sure to set its `delegate` 
+ and `hostViewController` properties.
+
+ @param apiAdapter    The API adapter the payment context will use to fetch and 
+ modify its contents. You need to make a class conforming to this protocol that 
+ talks to your server. @see STPBackendAPIAdapter.h
+ @param configuration The configuration for the payment context to use. This lets 
+ you set your Stripe publishable API key, required billing address fields, etc. 
+ @see STPPaymentConfiguration.h
+ @param theme         The theme describing the visual appearance of all UI that 
+ the payment context automatically creates for you. @see STPTheme.h
+
+ @return the newly-instantiated payment context
  */
 - (instancetype)initWithAPIAdapter:(id<STPBackendAPIAdapter>)apiAdapter
                      configuration:(STPPaymentConfiguration *)configuration
-                             theme:(STPTheme *)theme __attribute__((deprecated));
+                             theme:(STPTheme *)theme;
 
 /**
- The API adapter the payment context will use to fetch and modify its contents. You need to make a class conforming to this protocol that talks to your server. @see STPBackendAPIAdapter.h
-
- @deprecated Use `customerContext`.
- Instead of providing your own backend API adapter, you can now  create an
+ Note: Instead of providing your own backend API adapter, we recommend using
  `STPCustomerContext`, which will manage retrieving and updating a
  Stripe customer for you. @see STPCustomerContext.h
+
+ The API adapter the payment context will use to fetch and modify its contents. 
+ You need to make a class conforming to this protocol that talks to your server. 
+ @see STPBackendAPIAdapter.h
  */
-@property (nonatomic, readonly) id<STPBackendAPIAdapter> apiAdapter __attribute__((deprecated));
+@property (nonatomic, readonly) id<STPBackendAPIAdapter> apiAdapter;
 
 /**
  The configuration for the payment context to use internally. @see STPPaymentConfiguration.h

Stripe/PublicHeaders/STPPaymentMethodsViewController.h

@@ -75,6 +75,10 @@ NS_ASSUME_NONNULL_BEGIN
                              delegate:(id<STPPaymentMethodsViewControllerDelegate>)delegate;
 
 /**
+ Note: Instead of providing your own backend API adapter, we recommend using
+ `STPCustomerContext`, which will manage retrieving and updating a
+ Stripe customer for you. @see STPCustomerContext.h
+ 
  Initializes a new payment methods view controller without using 
  a payment context.
 
@@ -85,16 +89,11 @@ NS_ASSUME_NONNULL_BEGIN
  payment methods and save new ones.
  @param delegate      A delegate that will be notified when the payment methods 
  view controller's selection changes.
-
- @deprecated Use `initWithConfiguration:theme:customerContext:delegate:`.
- Instead of providing your own backend API adapter, you can now create an
- `STPCustomerContext`, which will manage retrieving and updating a
- Stripe customer for you. @see STPCustomerContext.h
  */
 - (instancetype)initWithConfiguration:(STPPaymentConfiguration *)configuration
                                 theme:(STPTheme *)theme
                            apiAdapter:(id<STPBackendAPIAdapter>)apiAdapter
-                             delegate:(id<STPPaymentMethodsViewControllerDelegate>)delegate DEPRECATED_MSG_ATTRIBUTE("Use `initWithConfiguration:theme:customerContext:delegate:` instead");
+                             delegate:(id<STPPaymentMethodsViewControllerDelegate>)delegate;
 
 /**
  If you've already collected some information from your user, you can set it

Stripe/STPCustomer.m

@@ -126,10 +126,6 @@ + (instancetype)decodedObjectFromAPIResponse:(NSDictionary *)response {
 
 @end
 
-/**
- NOTE: STPCustomerDeserializer has been deprecated. When we remove 
- STPBackendAPIAdapter, we should also remove STPCustomerDeserializer.
- */
 @interface STPCustomerDeserializer()
 
 @property (nonatomic, nullable) STPCustomer *customer;

Stripe/STPPaymentContext.m

@@ -45,10 +45,7 @@ @interface STPPaymentContext()<STPPaymentMethodsViewControllerDelegate, STPShipp
 
 @property (nonatomic) STPPaymentConfiguration *configuration;
 @property (nonatomic) STPTheme *theme;
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 @property (nonatomic) id<STPBackendAPIAdapter> apiAdapter;
-#pragma clang diagnostic pop
 @property (nonatomic) STPAPIClient *apiClient;
 @property (nonatomic) STPPromise<STPPaymentMethodTuple *> *loadingPromise;
 
@@ -75,8 +72,6 @@ @interface STPPaymentContext()<STPPaymentMethodsViewControllerDelegate, STPShipp
 
 @implementation STPPaymentContext
 
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 - (instancetype)initWithCustomerContext:(STPCustomerContext *)customerContext {
     return [self initWithAPIAdapter:customerContext];
 }
@@ -88,7 +83,6 @@ - (instancetype)initWithCustomerContext:(STPCustomerContext *)customerContext
                       configuration:configuration
                               theme:theme];
 }
-#pragma clang diagnostic pop
 
 - (instancetype)initWithAPIAdapter:(id<STPBackendAPIAdapter>)apiAdapter {
     return [self initWithAPIAdapter:apiAdapter

Stripe/STPPaymentMethodsInternalViewController.m

@@ -31,10 +31,7 @@
 @interface STPPaymentMethodsInternalViewController () <UITableViewDataSource, UITableViewDelegate, STPAddCardViewControllerDelegate>
 
 @property (nonatomic, strong, readwrite) STPPaymentConfiguration *configuration;
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 @property (nonatomic, strong, nullable, readwrite) id<STPBackendAPIAdapter> apiAdapter;
-#pragma clang diagnostic pop
 @property (nonatomic, strong, nullable, readwrite) STPUserInformation *prefilledInformation;
 @property (nonatomic, strong, nullable, readwrite) STPAddress *shippingAddress;
 @property (nonatomic, strong, readwrite) NSArray<id<STPPaymentMethod>> *paymentMethods;
@@ -139,6 +136,7 @@ - (BOOL)isPaymentMethodDetachable:(id<STPPaymentMethod>)paymentMethod {
     if (![self.apiAdapter respondsToSelector:@selector(detachSourceFromCustomer:completion:)]) {
         // Cannot detach payment methods if customerContext is an apiAdapter
         // that doesn't implement detachSource
+        return NO;
     }
 
     if (!paymentMethod) {

Stripe/STPPaymentMethodsViewController+Private.h

@@ -16,14 +16,11 @@
 
 @interface STPPaymentMethodsViewController (Private)
 
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 - (instancetype)initWithConfiguration:(STPPaymentConfiguration *)configuration
                            apiAdapter:(id<STPBackendAPIAdapter>)apiAdapter
                        loadingPromise:(STPPromise<STPPaymentMethodTuple *> *)loadingPromise
                                 theme:(STPTheme *)theme
                       shippingAddress:(STPAddress *)shippingAddress
                              delegate:(id<STPPaymentMethodsViewControllerDelegate>)delegate;
-#pragma clang diagnostic pop
 
 @end

Stripe/STPPaymentMethodsViewController.m

@@ -36,10 +36,7 @@ @interface STPPaymentMethodsViewController()<STPPaymentMethodsInternalViewContro
 
 @property (nonatomic) STPPaymentConfiguration *configuration;
 @property (nonatomic) STPAddress *shippingAddress;
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 @property (nonatomic) id<STPBackendAPIAdapter> apiAdapter;
-#pragma clang diagnostic pop
 @property (nonatomic) STPAPIClient *apiClient;
 @property (nonatomic) STPPromise<STPPaymentMethodTuple *> *loadingPromise;
 @property (nonatomic, weak) STPPaymentActivityIndicatorView *activityIndicator;
@@ -50,8 +47,6 @@ @interface STPPaymentMethodsViewController()<STPPaymentMethodsInternalViewContro
 
 @implementation STPPaymentMethodsViewController
 
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 - (instancetype)initWithPaymentContext:(STPPaymentContext *)paymentContext {
     return [self initWithConfiguration:paymentContext.configuration
                             apiAdapter:paymentContext.apiAdapter
@@ -96,7 +91,6 @@ - (instancetype)initWithConfiguration:(STPPaymentConfiguration *)configuration
     }];
     return promise;
 }
-#pragma clang diagnostic pop
 
 - (void)createAndSetupViews {
     [super createAndSetupViews];
@@ -245,8 +239,6 @@ - (void)dismissWithCompletion:(STPVoidBlock)completion {
 
 @implementation STPPaymentMethodsViewController (Private)
 
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 - (instancetype)initWithConfiguration:(STPPaymentConfiguration *)configuration
                            apiAdapter:(id<STPBackendAPIAdapter>)apiAdapter
                        loadingPromise:(STPPromise<STPPaymentMethodTuple *> *)loadingPromise
@@ -290,6 +282,5 @@ - (instancetype)initWithConfiguration:(STPPaymentConfiguration *)configuration
     }
     return self;
 }
-#pragma clang diagnostic pop
 
 @end