📝 Documentation updates

Author: pboling

.rubocop_gradual.lock

@@ -6,7 +6,7 @@
   "lib/oauth2.rb:4176768025": [
     [38, 11, 7, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 651502127]
   ],
-  "lib/oauth2/access_token.rb:569882683": [
+  "lib/oauth2/access_token.rb:3471244990": [
     [49, 13, 5, "Style/IdenticalConditionalBranches: Move `t_key` out of the conditional.", 183811513],
     [55, 13, 5, "Style/IdenticalConditionalBranches: Move `t_key` out of the conditional.", 183811513]
   ],

lib/oauth2/access_token.rb

@@ -164,17 +164,24 @@ def expires?
       !!@expires_at
     end
 
-    # Whether the token is expired
+    # Check if token is expired
     #
-    # @return [Boolean]
+    # @return [Boolean] true if the token is expired, false otherwise
     def expired?
       expires? && (expires_at <= Time.now.to_i)
     end
 
     # Refreshes the current Access Token
     #
-    # @return [AccessToken] a new AccessToken
-    # @note options should be carried over to the new AccessToken
+    # @param [Hash] params additional params to pass to the refresh token request
+    # @param [Hash] access_token_opts options that will be passed to the AccessToken initialization
+    #
+    # @yield [opts] The block to modify the refresh token request options
+    # @yieldparam [Hash] opts The options hash that can be modified
+    #
+    # @return [OAuth2::AccessToken] a new AccessToken instance
+    #
+    # @note current token's options are carried over to the new AccessToken
     def refresh(params = {}, access_token_opts = {}, &block)
       raise OAuth2::Error.new({error: "A refresh_token is not available"}) unless refresh_token
 
@@ -282,7 +289,16 @@ def to_hash
     # @param [Symbol] verb the HTTP request method
     # @param [String] path the HTTP URL path of the request
     # @param [Hash] opts the options to make the request with
-    #   @see Client#request
+    # @option opts [Hash] :params additional URL parameters
+    # @option opts [Hash, String] :body the request body
+    # @option opts [Hash] :headers request headers
+    #
+    # @yield [req] The block to modify the request
+    # @yieldparam [Faraday::Request] req The request object that can be modified
+    #
+    # @return [OAuth2::Response] the response from the request
+    #
+    # @see OAuth2::Client#request
     def request(verb, path, opts = {}, &block)
       configure_authentication!(opts)
       @client.request(verb, path, opts, &block)

lib/oauth2/client.rb

@@ -72,13 +72,16 @@ def initialize(client_id, client_secret, options = {}, &block)
 
     # Set the site host
     #
-    # @param value [String] the OAuth2 provider site host
+    # @param [String] value the OAuth2 provider site host
+    # @return [String] the site host value
     def site=(value)
       @connection = nil
       @site = value
     end
 
     # The Faraday connection object
+    #
+    # @return [Faraday::Connection] the initialized Faraday connection
     def connection
       @connection ||=
         Faraday.new(site, options[:connection_opts]) do |builder|
@@ -95,32 +98,36 @@ def connection
     # The authorize endpoint URL of the OAuth2 provider
     #
     # @param [Hash] params additional query parameters
+    # @return [String] the constructed authorize URL
     def authorize_url(params = {})
       params = (params || {}).merge(redirection_params)
       connection.build_url(options[:authorize_url], params).to_s
     end
 
     # The token endpoint URL of the OAuth2 provider
     #
-    # @param [Hash] params additional query parameters
+    # @param [Hash, nil] params additional query parameters
+    # @return [String] the constructed token URL
     def token_url(params = nil)
       connection.build_url(options[:token_url], params).to_s
     end
 
     # The revoke endpoint URL of the OAuth2 provider
     #
-    # @param [Hash] params additional query parameters
+    # @param [Hash, nil] params additional query parameters
+    # @return [String] the constructed revoke URL
     def revoke_url(params = nil)
       connection.build_url(options[:revoke_url], params).to_s
     end
 
     # Makes a request relative to the specified site root.
+    #
     # Updated HTTP 1.1 specification (IETF RFC 7231) relaxed the original constraint (IETF RFC 2616),
     #   allowing the use of relative URLs in Location headers.
     #
     # @see https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.2
     #
-    # @param [Symbol] verb one of :get, :post, :put, :delete
+    # @param [Symbol] verb one of [:get, :post, :put, :delete]
     # @param [String] url URL path of request
     # @param [Hash] opts the options to make the request with
     # @option req_opts [Hash] :params additional query parameters for the URL of the request
@@ -129,9 +136,13 @@ def revoke_url(params = nil)
     # @option req_opts [Boolean] :raise_errors whether to raise an OAuth2::Error on 400+ status
     #   code response for this request.  Overrides the client instance setting.
     # @option req_opts [Symbol] :parse @see Response::initialize
-    # @option req_opts [true, false] :snaky (true) @see Response::initialize
+    # @option req_opts [Boolean] :snaky (true) @see Response::initialize
     #
-    # @yield [req] @see Faraday::Connection#run_request
+    # @yield [req] The block is passed the request being made, allowing customization
+    # @yieldparam [Faraday::Request] req The request object that can be modified
+    # @see Faraday::Connection#run_request
+    #
+    # @return [OAuth2::Response] the response from the request
     def request(verb, url, req_opts = {}, &block)
       response = execute_request(verb, url, req_opts, &block)
       status = response.status
@@ -532,4 +543,4 @@ def oauth_debug_logging(builder)
       builder.response(:logger, options[:logger], bodies: true) if OAuth2::OAUTH_DEBUG
     end
   end
-end
+end