Merge pull request #684 from ruby-oauth/feat/improve-docs

Author: pboling

CHANGELOG.md

@@ -20,6 +20,8 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Added
 
+- [gh!683][gh!683] Improve documentation by @pboling
+
 ### Changed
 
 ### Deprecated
@@ -30,6 +32,8 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+[gh!683]: https://github.com/ruby-oauth/oauth2/pull/683
+
 ## [2.0.17] - 2025-09-15
 
 - TAG: [v2.0.17][2.0.17t]
@@ -41,6 +45,8 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - [gh!682][gh!682] - AccessToken: support Hash-based verb-dependent token transmission mode (e.g., {get: :query, post: :header})
 
+[gh!682]: https://github.com/ruby-oauth/oauth2/pull/682
+
 ## [2.0.16] - 2025-09-14
 
 - TAG: [v2.0.16][2.0.16t]

README.md

@@ -62,9 +62,10 @@ NOTE: `header` - The content type specified in the `curl` is already the default
 </details>
 
 <details>
-<summary>Complete E2E single file script against [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server)</summary>
+<summary>Complete E2E single file script against mock-oauth2-server</summary>
 
-- E2E example using the mock test server added in v2.0.11
+- E2E example uses [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server), which was added in v2.0.11
+- E2E example does not ship with the released gem, so clone the source to play with it.
 
 ```console
 docker compose -f docker-compose-ssl.yml up -d --wait
@@ -93,26 +94,26 @@ docker compose -f docker-compose-ssl.yml down
 Troubleshooting: validate connectivity to the mock server
 
 - Check container status and port mapping:
-    - docker compose -f docker-compose-ssl.yml ps
+    - `docker compose -f docker-compose-ssl.yml ps`
 - From the host, try the discovery URL directly (this is what the example uses by default):
-    - curl -v http://localhost:8080/default/.well-known/openid-configuration
-    - If that fails immediately, also try: curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration
-- From inside the container (to distinguish container vs host networking):
-    - docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration
+    - `curl -v http://localhost:8080/default/.well-known/openid-configuration`
+    - If that fails immediately, also try: `curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration`
+- From inside the container (to distinguish container vs. host networking):
+    - `docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration`
 - Simple TCP probe from the host:
-    - nc -vz localhost 8080  # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"'
+    - `nc -vz localhost 8080  # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"'`
 - Inspect which host port 8080 is bound to (should be 8080):
-    - docker inspect -f '{{ (index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }}' oauth2-mock-oauth2-server-1
+    - `docker inspect -f '{{ (index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }}' oauth2-mock-oauth2-server-1`
 - Look at server logs for readiness/errors:
-    - docker logs -n 200 oauth2-mock-oauth2-server-1
+    - `docker logs -n 200 oauth2-mock-oauth2-server-1`
 - On Linux, ensure nothing else is bound to 8080 and that firewall/SELinux aren’t blocking:
-    - ss -ltnp | grep :8080
+    - `ss -ltnp | grep :8080`
 
 Notes
-- Discovery URL pattern is: http://localhost:8080/<realm>/.well-known/openid-configuration, where <realm> defaults to "default".
+- Discovery URL pattern is: `http://localhost:8080/<realm>/.well-known/openid-configuration`, where `<realm>` defaults to `default`.
 - You can change these with env vars when running the example:
-    - E2E_ISSUER_BASE (default: http://localhost:8080)
-    - E2E_REALM (default: default)
+    - `E2E_ISSUER_BASE` (default: http://localhost:8080)
+    - `E2E_REALM` (default: default)
 
 </details>
 
@@ -144,7 +145,7 @@ If it seems like you are in the wrong place, you might try one of these:
 
 ### Compatibility
 
-* Operating Systems: Linux, MacOS, Windows
+* Operating Systems: Linux, macOS, Windows
 * MRI Ruby @ v2.3, v2.4, v2.5, v2.6, v2.7, v3.0, v3.1, v3.2, v3.3, v3.4, HEAD
     * NOTE: This gem may still _install_ and _run_ on ruby v2.2, but vanilla GitHub Actions no longer supports testing against it, so YMMV. Accept patches so long as they don't break the platforms that do run in CI.
 * JRuby @ v9.4, v10.0, HEAD
@@ -213,7 +214,7 @@ The various versions of each are tested via the Ruby test matrix, along with wha
 * time
 * logger (removed from stdlib in Ruby 3.5 so added as runtime dependency in v2.0.10)
 
-If you use a gem version of a core Ruby library it should work fine!
+If you use a gem version of a core Ruby library, it should work fine!
 
 </details>
 
@@ -413,11 +414,11 @@ gem install oauth2
 <details>
   <summary>For Medium or High Security Installations</summary>
 
-This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by
+This gem is cryptographically signed and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by
 [stone_checksums][💎stone_checksums]. Be sure the gem you install hasn’t been tampered with
 by following the instructions below.
 
-Add my public key (if you haven’t already, expires 2045-04-29) as a trusted certificate:
+Add my public key (if you haven’t already; will expire 2045-04-29) as a trusted certificate:
 
 ```console
 gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem)
@@ -492,7 +493,7 @@ see [gemfiles/README.md](gemfiles/README.md), then submit a PR to the correct ma
 If something doesn't work on one of these interpreters, it's a bug.
 
 This library may inadvertently work (or seem to work) on other Ruby
-implementations, however support will only be provided for the versions listed
+implementations; however, support will only be provided for the versions listed
 above.
 
 If you would like this library to support another Ruby version, you may
@@ -531,13 +532,13 @@ Some OAuth 2.0 standards legitimately have multiple tokens.
 You may need to subclass `OAuth2::AccessToken`, or write your own custom alternative to it, and pass it in.
 Specify your custom class with the `access_token_class` option.
 
-If you only need one token you can, as of v2.0.10,
+If you only need one token, you can, as of v2.0.10,
 specify the exact token name you want to extract via the `OAuth2::AccessToken` using
 the `token_name` option.
 
 You'll likely need to do some source diving.
 This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas.
-If you have time and energy please contribute to the documentation!
+If you have time and energy, please contribute to the documentation!
 
 ## 🔧 Basic Usage
 
@@ -558,7 +559,7 @@ response.class.name
 
 ### Relative `authorize_url` and `token_url` (Not on site root, Just Works!)
 
-In above example, the default Authorization URL is `oauth/authorize` and default Access Token URL is `oauth/token`, and, as they are missing a leading `/`, both are relative.
+In the above example, the default Authorization URL is `oauth/authorize` and default Access Token URL is `oauth/token`, and, as they are missing a leading `/`, both are relative.
 
 ```ruby
 client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/nested/directory/on/your/server")
@@ -751,16 +752,18 @@ a hash of the values), or `from_kvform` (if you have an
 `application/x-www-form-urlencoded` encoded string of the values).
 
 Options (since v2.0.x unless noted):
-- expires_latency (Integer | nil): Seconds to subtract from expires_in when computing #expired? to offset latency.
-- token_name (String | Symbol | nil): When multiple token-like fields exist in responses, select the field name to use as the access token (since v2.0.10).
-- mode (Symbol | Proc | Hash): Controls how the token is transmitted on requests made via this AccessToken instance.
-  - :header — Send as Authorization: Bearer <token> header (default and preferred by OAuth 2.1 draft guidance).
-  - :query — Send as access_token query parameter (discouraged in general, but required by some providers).
+- `expires_latency` (Integer | nil): Seconds to subtract from expires_in when computing #expired? to offset latency.
+- `token_name` (String | Symbol | nil): When multiple token-like fields exist in responses, select the field name to use as the access token (since v2.0.10).
+- `mode` (Symbol | Proc | Hash): Controls how the token is transmitted on requests made via this AccessToken instance.
+  - `:header` — Send as Authorization: Bearer <token> header (default and preferred by OAuth 2.1 draft guidance).
+  - `:query` — Send as access_token query parameter (discouraged in general, but required by some providers).
   - Verb-dependent (since v2.0.15): Provide either:
-    - a Proc taking |verb| and returning :header or :query, or
-    - a Hash with verb symbols as keys, for example: {get: :query, post: :header, delete: :header}.
+    - a `Proc` taking `|verb|` and returning `:header` or `:query`, or
+    - a `Hash` with verb symbols as keys, for example `{get: :query, post: :header, delete: :header}`.
 
-Note: Verb-dependent mode was added in v2.0.15 to support providers like Instagram that require query mode for GET and header mode for POST/DELETE.
+Note: Verb-dependent mode supports providers like Instagram that require query mode for `GET` and header mode for `POST`/`DELETE`
+- Verb-dependent mode via `Proc` was added in v2.0.15
+- Verb-dependent mode via `Hash` was added in v2.0.16
 
 ### OAuth2::Error
 

docs/OAuth2.html

@@ -415,7 +415,7 @@ <h3 class="signature first" id="configure-class_method">
 </div>
 
       <div id="footer">
-  Generated on Mon Sep 15 21:28:40 2025 by
+  Generated on Tue Sep 16 00:53:52 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/AccessToken.html

@@ -3083,7 +3083,7 @@ <h3 class="signature " id="to_hash-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Mon Sep 15 21:28:40 2025 by
+  Generated on Tue Sep 16 00:53:52 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/Authenticator.html

@@ -883,7 +883,7 @@ <h3 class="signature first" id="apply-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Mon Sep 15 21:28:40 2025 by
+  Generated on Tue Sep 16 00:53:52 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/Client.html

@@ -2656,7 +2656,7 @@ <h3 class="signature " id="token_url-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Mon Sep 15 21:28:40 2025 by
+  Generated on Tue Sep 16 00:53:52 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/Error.html

@@ -772,7 +772,7 @@ <h3 class="signature " id="response-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Mon Sep 15 21:28:40 2025 by
+  Generated on Tue Sep 16 00:53:52 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/FilteredAttributes.html

@@ -335,7 +335,7 @@ <h3 class="signature first" id="inspect-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Mon Sep 15 21:28:40 2025 by
+  Generated on Tue Sep 16 00:53:52 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/FilteredAttributes/ClassMethods.html

@@ -280,7 +280,7 @@ <h3 class="signature " id="filtered_attributes-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Mon Sep 15 21:28:40 2025 by
+  Generated on Tue Sep 16 00:53:52 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/OAuth2/Response.html

@@ -1619,7 +1619,7 @@ <h3 class="signature " id="status-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Mon Sep 15 21:28:40 2025 by
+  Generated on Tue Sep 16 00:53:52 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>