Merge pull request #692 from ruby-oauth/feat/docs

Author: pboling

Gemfile.lock

@@ -311,7 +311,7 @@ GEM
     uri (1.1.1)
     version_gem (1.1.9)
     yard (0.9.37)
-    yard-fence (0.5.0)
+    yard-fence (0.7.0)
       rdoc (~> 6.11)
       version_gem (~> 1.1, >= 1.1.9)
       yard (~> 0.9, >= 0.9.37)

README.md

@@ -471,7 +471,7 @@ Expand the examples below, or the [ruby-oauth/snaky_hash](https://gitlab.com/rub
 or [response_spec.rb](https://github.com/ruby-oauth/oauth2/blob/main/spec/oauth2/response_spec.rb), for more ideas, especially if you need to study the hacks for older Rubies.
 
 <details markdown="1">
-<summary>See Examples</summary>
+  <summary>See Examples</summary>
 
 ```ruby
 class MySnakyHash < SnakyHash::StringKeyed

docs/OAuth2.html

@@ -119,8 +119,8 @@ <h2>
         <dt id="OAUTH_DEBUG-constant" class="">OAUTH_DEBUG =
           <div class="docstring">
   <div class="discussion">
-    <p>When true, enables verbose HTTP logging via Faraday’s logger middleware.
-Controlled by the OAUTH_DEBUG environment variable. Any case-insensitive
+    <p>When true, enables verbose HTTP logging via Faraday’s logger middleware.<br />
+Controlled by the OAUTH_DEBUG environment variable. Any case-insensitive<br />
 value equal to “true” will enable debugging.</p>
 
 
@@ -415,7 +415,7 @@ <h3 class="signature first" id="configure-class_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Nov  7 21:14:33 2025 by
+  Generated on Sat Nov  8 00:26:51 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>

docs/OAuth2/AccessToken.html

@@ -826,13 +826,13 @@ <h3 class="signature first" id="initialize-instance_method">
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If no token is provided, the AccessToken will be considered invalid.
-This is to prevent the possibility of a token being accidentally
-created with no token value.
-If you want to create an AccessToken with no token value,
-you can pass in an empty string or nil for the token value.
-If you want to create an AccessToken with no token value and
-no refresh token, you can pass in an empty string or nil for the
+    <div class='inline'><p>If no token is provided, the AccessToken will be considered invalid.<br />
+This is to prevent the possibility of a token being accidentally<br />
+created with no token value.<br />
+If you want to create an AccessToken with no token value,<br />
+you can pass in an empty string or nil for the token value.<br />
+If you want to create an AccessToken with no token value and<br />
+no refresh token, you can pass in an empty string or nil for the<br />
 token value and nil for the refresh token, and <code>raise_errors: false</code>.</p>
 </div>
   </div>
@@ -987,9 +987,9 @@ <h5 class="example_title"><div class='inline'><p>Verb-dependent Hash mode</p>
 
           </span>
 
-            &mdash; <div class='inline'><p>the transmission mode of the Access Token parameter value:
-either one of :header, :body or :query; or a Hash with verb symbols as keys mapping to one of these symbols
-(e.g., <code>{get: :query, post: :header, delete: :header}</code>); or a callable that accepts a request-verb parameter
+            &mdash; <div class='inline'><p>the transmission mode of the Access Token parameter value:<br />
+either one of :header, :body or :query; or a Hash with verb symbols as keys mapping to one of these symbols<br />
+(e.g., <code>{get: :query, post: :header, delete: :header}</code>); or a callable that accepts a request-verb parameter<br />
 and returns one of these three symbols.</p>
 </div>
 
@@ -1020,7 +1020,7 @@ <h5 class="example_title"><div class='inline'><p>Verb-dependent Hash mode</p>
 
           </span>
 
-            &mdash; <div class='inline'><p>the parameter name to use for transmission of the
+            &mdash; <div class='inline'><p>the parameter name to use for transmission of the<br />
 Access Token value in :body or :query transmission mode</p>
 </div>
 
@@ -1036,7 +1036,7 @@ <h5 class="example_title"><div class='inline'><p>Verb-dependent Hash mode</p>
 
           </span>
 
-            &mdash; <div class='inline'><p>the name of the response parameter that identifies the access token
+            &mdash; <div class='inline'><p>the name of the response parameter that identifies the access token<br />
 When nil one of TOKEN_KEY_LOOKUP will be used</p>
 </div>
 
@@ -1533,21 +1533,21 @@ <h3 class="signature first" id="from_hash-class_method">
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>The method will use the first found token key in the following order:
+    <div class='inline'><p>The method will use the first found token key in the following order:<br />
 ‘access_token’, ‘id_token’, ‘token’ (or their symbolic versions)</p>
 </div>
   </div>
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If multiple token keys are present, a warning will be issued unless
+    <div class='inline'><p>If multiple token keys are present, a warning will be issued unless<br />
 OAuth2.config.silence_extra_tokens_warning is true</p>
 </div>
   </div>
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If no token keys are present, a warning will be issued unless
+    <div class='inline'><p>If no token keys are present, a warning will be issued unless<br />
 OAuth2.config.silence_no_tokens_warning is true</p>
 </div>
   </div>
@@ -2746,28 +2746,28 @@ <h3 class="signature " id="revoke-instance_method">
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If the token passed to the request
-is an access token, the server MAY revoke the respective refresh
+    <div class='inline'><p>If the token passed to the request<br />
+is an access token, the server MAY revoke the respective refresh<br />
 token as well.</p>
 </div>
   </div>
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If the token passed to the request
-is a refresh token and the authorization server supports the
-revocation of access tokens, then the authorization server SHOULD
-also invalidate all access tokens based on the same authorization
+    <div class='inline'><p>If the token passed to the request<br />
+is a refresh token and the authorization server supports the<br />
+revocation of access tokens, then the authorization server SHOULD<br />
+also invalidate all access tokens based on the same authorization<br />
 grant</p>
 </div>
   </div>
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If the server responds with HTTP status code 503, your code must
-assume the token still exists and may retry after a reasonable delay.
-The server may include a “Retry-After” header in the response to
-indicate how long the service is expected to be unavailable to the
+    <div class='inline'><p>If the server responds with HTTP status code 503, your code must<br />
+assume the token still exists and may retry after a reasonable delay.<br />
+The server may include a “Retry-After” header in the response to<br />
+indicate how long the service is expected to be unavailable to the<br />
 requesting client.</p>
 </div>
   </div>
@@ -3083,7 +3083,7 @@ <h3 class="signature " id="to_hash-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Nov  7 21:14:34 2025 by
+  Generated on Sat Nov  8 00:26:51 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>

docs/OAuth2/Authenticator.html

@@ -108,7 +108,7 @@ <h2>Overview</h2><div class="docstring">
   <div class="discussion">
     <p>Builds and applies client authentication to token and revoke requests.</p>
 
-<p>Depending on the selected mode, credentials are applied as Basic Auth
+<p>Depending on the selected mode, credentials are applied as Basic Auth<br />
 headers, request body parameters, or only the client_id is sent (TLS).</p>
 
 
@@ -788,7 +788,7 @@ <h3 class="signature first" id="apply-instance_method">
   <div class="discussion">
     <p>Apply the request credentials used to authenticate to the Authorization Server</p>
 
-<p>Depending on the configuration, this might be as request params or as an
+<p>Depending on the configuration, this might be as request params or as an<br />
 Authorization header.</p>
 
 <p>User-provided params and header take precedence.</p>
@@ -883,7 +883,7 @@ <h3 class="signature first" id="apply-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Nov  7 21:14:34 2025 by
+  Generated on Sat Nov  8 00:26:51 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>

docs/OAuth2/Client.html

@@ -1243,7 +1243,7 @@ <h3 class="signature first" id="assertion-instance_method">
   <div class="discussion">
     <p>The Assertion strategy</p>
 
-<p>This allows for assertion-based authentication where an identity provider
+<p>This allows for assertion-based authentication where an identity provider<br />
 asserts the identity of the user or client application seeking access.</p>
 
 
@@ -1487,7 +1487,7 @@ <h3 class="signature " id="get_token-instance_method">
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>The extract_access_token parameter is deprecated and will be removed in oauth2 v3.
+    <div class='inline'><p>The extract_access_token parameter is deprecated and will be removed in oauth2 v3.<br />
 Use access_token_class on initialization instead.</p>
 </div>
   </div>
@@ -1523,10 +1523,12 @@ <h4 class="tag_title">Examples:</h4>
 
 
         &mdash;
-        <div class='inline'><p>a Hash of params for the token endpoint
-* params can include a ‘headers’ key with a Hash of request headers
-* params can include a ‘parse’ key with the Symbol name of response parsing strategy (default: :automatic)
-* params can include a ‘snaky’ key to control snake_case conversion (default: false)</p>
+        <div class='inline'><p>a Hash of params for the token endpoint</p>
+<ul>
+  <li>params can include a ‘headers’ key with a Hash of request headers</li>
+  <li>params can include a ‘parse’ key with the Symbol name of response parsing strategy (default: :automatic)</li>
+  <li>params can include a ‘snaky’ key to control snake_case conversion (default: false)</li>
+</ul>
 </div>
 
     </li>
@@ -1614,7 +1616,7 @@ <h4 class="tag_title">Examples:</h4>
 
 
         &mdash;
-        <div class='inline'><p>the initialized AccessToken instance, or nil if token extraction fails
+        <div class='inline'><p>the initialized AccessToken instance, or nil if token extraction fails<br />
 and raise_errors is false</p>
 </div>
 
@@ -1837,14 +1839,14 @@ <h3 class="signature " id="redirection_params-instance_method">
   <div class="discussion">
     <p>The redirect_uri parameters, if configured</p>
 
-<p>The redirect_uri query parameter is OPTIONAL (though encouraged) when
-requesting authorization. If it is provided at authorization time it MUST
+<p>The redirect_uri query parameter is OPTIONAL (though encouraged) when<br />
+requesting authorization. If it is provided at authorization time it MUST<br />
 also be provided with the token exchange request.</p>
 
-<p>OAuth 2.1 note: Authorization Servers must compare redirect URIs using exact string matching.
+<p>OAuth 2.1 note: Authorization Servers must compare redirect URIs using exact string matching.<br />
 This client simply forwards the configured redirect_uri; the exact-match validation happens server-side.</p>
 
-<p>Providing :redirect_uri to the OAuth2::Client instantiation will take
+<p>Providing :redirect_uri to the OAuth2::Client instantiation will take<br />
 care of managing this.</p>
 
 
@@ -1927,7 +1929,7 @@ <h3 class="signature " id="request-instance_method">
   <div class="discussion">
     <p>Makes a request relative to the specified site root.</p>
 
-<p>Updated HTTP 1.1 specification (IETF RFC 7231) relaxed the original constraint (IETF RFC 2616),
+<p>Updated HTTP 1.1 specification (IETF RFC 7231) relaxed the original constraint (IETF RFC 2616),<br />
   allowing the use of relative URLs in Location headers.</p>
 
 
@@ -2039,7 +2041,7 @@ <h3 class="signature " id="request-instance_method">
 
           </span>
 
-            &mdash; <div class='inline'><p>whether to raise an OAuth2::Error on 400+ status
+            &mdash; <div class='inline'><p>whether to raise an OAuth2::Error on 400+ status<br />
 code response for this request.  Overrides the client instance setting.</p>
 </div>
 
@@ -2241,28 +2243,28 @@ <h3 class="signature " id="revoke_token-instance_method">
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If the token passed to the request
-is an access token, the server MAY revoke the respective refresh
+    <div class='inline'><p>If the token passed to the request<br />
+is an access token, the server MAY revoke the respective refresh<br />
 token as well.</p>
 </div>
   </div>
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If the token passed to the request
-is a refresh token and the authorization server supports the
-revocation of access tokens, then the authorization server SHOULD
-also invalidate all access tokens based on the same authorization
+    <div class='inline'><p>If the token passed to the request<br />
+is a refresh token and the authorization server supports the<br />
+revocation of access tokens, then the authorization server SHOULD<br />
+also invalidate all access tokens based on the same authorization<br />
 grant</p>
 </div>
   </div>
 
   <div class="note notetag">
     <strong>Note:</strong>
-    <div class='inline'><p>If the server responds with HTTP status code 503, your code must
-assume the token still exists and may retry after a reasonable delay.
-The server may include a “Retry-After” header in the response to
-indicate how long the service is expected to be unavailable to the
+    <div class='inline'><p>If the server responds with HTTP status code 503, your code must<br />
+assume the token still exists and may retry after a reasonable delay.<br />
+The server may include a “Retry-After” header in the response to<br />
+indicate how long the service is expected to be unavailable to the<br />
 requesting client.</p>
 </div>
   </div>
@@ -2654,7 +2656,7 @@ <h3 class="signature " id="token_url-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Nov  7 21:14:33 2025 by
+  Generated on Sat Nov  8 00:26:51 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>

docs/OAuth2/Error.html

@@ -105,7 +105,7 @@ <h2>Overview</h2><div class="docstring">
   <div class="discussion">
     <p>Represents an OAuth2 error condition.</p>
 
-<p>Wraps details from an OAuth2::Response or Hash payload returned by an
+<p>Wraps details from an OAuth2::Response or Hash payload returned by an<br />
 authorization server, exposing error code and description per RFC 6749.</p>
 
 
@@ -772,7 +772,7 @@ <h3 class="signature " id="response-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Nov  7 21:14:33 2025 by
+  Generated on Sat Nov  8 00:26:51 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>

docs/OAuth2/FilteredAttributes.html

@@ -92,8 +92,8 @@ <h2>Overview</h2><div class="docstring">
   <div class="discussion">
     <p>Mixin that redacts sensitive instance variables in #inspect output.</p>
 
-<p>Classes include this module and declare which attributes should be filtered
-using filtered_attributes. Any instance variable name that includes one of
+<p>Classes include this module and declare which attributes should be filtered<br />
+using filtered_attributes. Any instance variable name that includes one of<br />
 those attribute names will be shown as [FILTERED] in the object’s inspect.</p>
 
 
@@ -202,7 +202,7 @@ <h3 class="signature first" id="included-class_method">
 
 </h3><div class="docstring">
   <div class="discussion">
-    <p class="note returns_void">This method returns an undefined value.</p><p>Hook invoked when the module is included. Extends the including class with
+    <p class="note returns_void">This method returns an undefined value.</p><p>Hook invoked when the module is included. Extends the including class with<br />
 class-level helpers.</p>
 
 
@@ -335,7 +335,7 @@ <h3 class="signature first" id="inspect-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Nov  7 21:14:33 2025 by
+  Generated on Sat Nov  8 00:26:51 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>

docs/OAuth2/FilteredAttributes/ClassMethods.html

@@ -280,7 +280,7 @@ <h3 class="signature " id="filtered_attributes-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Nov  7 21:14:33 2025 by
+  Generated on Sat Nov  8 00:26:51 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.7).
 </div>