README.md in stripe-5.14.0 vs README.md in stripe-5.15.0

@@ -12,12 +12,10 @@
 
 The library also provides other features. For example:
 
 - Easy configuration path for fast setup and use.
 - Helpers for pagination.
-- Tracking of "fresh" values in API resources so that partial updates can be
-  executed.
 - Built-in mechanisms for the serialization of parameters according to the
   expectations of Stripe's API.
 
 ## Documentation
 
@@ -63,17 +61,15 @@
 
 ```ruby
 require "stripe"
 Stripe.api_key = "sk_test_..."
 
-# list charges
-Stripe::Charge.list()
+# list customers
+Stripe::Customer.list()
 
-# retrieve single charge
-Stripe::Charge.retrieve(
-  "ch_18atAXCdGbJFKhCuBAa4532Z",
-)
+# retrieve single customer
+Stripe::Customer.retrieve("cus_123456789")
 ```
 
 ### Per-request Configuration
 
 For apps that need to use multiple keys during the lifetime of a process, like
@@ -81,50 +77,51 @@
 per-request key and/or account:
 
 ```ruby
 require "stripe"
 
-Stripe::Charge.list(
+Stripe::Customer.list(
   {},
   {
     api_key: "sk_test_...",
     stripe_account: "acct_...",
     stripe_version: "2018-02-28",
   }
 )
 
-Stripe::Charge.retrieve(
-  "ch_18atAXCdGbJFKhCuBAa4532Z",
+Stripe::Customer.retrieve(
+  "cus_123456789",
   {
     api_key: "sk_test_...",
     stripe_account: "acct_...",
     stripe_version: "2018-02-28",
   }
 )
 
-Stripe::Charge.retrieve(
+Stripe::Customer.retrieve(
   {
-    id: "ch_18atAXCdGbJFKhCuBAa4532Z",
+    id: "cus_123456789",
     expand: %w(balance_transaction)
   },
   {
     stripe_version: "2018-02-28",
     api_key: "sk_test_...",
   }
 )
 
-Stripe::Charge.capture(
-  "ch_18atAXCdGbJFKhCuBAa4532Z",
+Stripe::Customer.capture(
+  "cus_123456789",
   {},
   {
     stripe_version: "2018-02-28",
     api_key: "sk_test_...",
   }
 )
 ```
 
 Keep in mind that there are different method signatures depending on the action:
+
 - When operating on a collection (e.g. `.list`, `.create`) the method signature is
   `method(params, opts)`.
 - When operating on resource (e.g. `.capture`, `.update`) the method signature is
   `method(id, params, opts)`.
 - One exception is that `retrieve`, despite being an operation on a resource, has the signature
@@ -136,14 +133,12 @@
 Get access to response objects by initializing a client and using its `request`
 method:
 
 ```ruby
 client = Stripe::StripeClient.new
-charge, resp = client.request do
-  Stripe::Charge.retrieve(
-    "ch_18atAXCdGbJFKhCuBAa4532Z",
-  )
+customer, resp = client.request do
+  Stripe::Customer.retrieve("cus_123456789",)
 end
 puts resp.request_id
 ```
 
 ### Configuring a proxy
@@ -222,22 +217,46 @@
    Stripe.log_level = Stripe::LEVEL_INFO
    ```
 
 ### Instrumentation
 
-The library has a hook for when a HTTP call is made which can be used for
-monitoring. The callback receives a `RequestEvent` object with the following
-data:
-- HTTP method (`Symbol`)
-- request path (`String`)
-- HTTP response code (`Integer`) if available, or `nil` in case of a lower
-  level network error
-- request duration in seconds (`Float`)
-- the number of retries (`Integer`)
+The library has various hooks that user code can tie into by passing a block to
+`Stripe::Instrumentation.subscribe` to be notified about specific events.
 
+#### `request_begin`
+
+Invoked when an HTTP request starts. Receives `RequestBeginEvent` with the
+following properties:
+
+- `method`: HTTP method. (`Symbol`)
+- `num_retries`: The number of retries. (`Integer`)
+- `user_data`: A hash on which users can set arbitrary data, and which will be
+  passed through to `request_end` invocations. This could be used, for example,
+  to assign unique IDs to each request, and it'd work even if many requests are
+  running in parallel. All subscribers share the same object for any particular
+  request, so they must be careful to use unique keys that will not conflict
+  with other subscribers. (`Hash`)
+
+#### `request_end`
+
+Invoked when an HTTP request finishes, regardless of whether it terminated with
+a success or error. Receives `RequestEndEvent` with the following properties:
+
+- `duration`: Request duration in seconds. (`Float`)
+- `http_status`: HTTP response code (`Integer`) if available, or `nil` in case
+  of a lower level network error.
+- `method`: HTTP method. (`Symbol`)
+- `num_retries`: The number of retries. (`Integer`)
+- `path`: Request path. (`String`)
+- `user_data`: A hash on which users may have set arbitrary data in
+  `request_begin`. See above for more information. (`Hash`)
+
+#### Example
+
 For example:
+
 ```ruby
-Stripe::Instrumentation.subscribe(:request) do |request_event|
+Stripe::Instrumentation.subscribe(:request_end) do |request_event|
   tags = {
     method: request_event.method,
     resource: request_event.path.split("/")[2],
     code: request_event.http_status,
     retries: request_event.num_retries