From 17e326814dce15ff9be3bdca7d3e3f6deb5a98d9 Mon Sep 17 00:00:00 2001
From: Joakim Antman <antmanj@gmail.com>
Date: Sat, 7 Dec 2024 17:26:28 +0200
Subject: [PATCH] Documentation for modules and classes

---
 .rubocop.yml                     | 3 ---
 lib/jwt/deprecations.rb          | 1 +
 lib/jwt/encoded_token.rb         | 4 ++--
 lib/jwt/json.rb                  | 2 +-
 lib/jwt/jwa/ecdsa.rb             | 1 +
 lib/jwt/jwa/eddsa.rb             | 1 +
 lib/jwt/jwa/hmac.rb              | 1 +
 lib/jwt/jwa/hmac_rbnacl.rb       | 1 +
 lib/jwt/jwa/hmac_rbnacl_fixed.rb | 1 +
 lib/jwt/jwa/none.rb              | 1 +
 lib/jwt/jwa/ps.rb                | 1 +
 lib/jwt/jwa/rsa.rb               | 1 +
 lib/jwt/jwa/signing_algorithm.rb | 3 +++
 lib/jwt/jwa/unsupported.rb       | 1 +
 lib/jwt/jwa/wrapper.rb           | 1 +
 lib/jwt/jwk.rb                   | 1 +
 lib/jwt/jwk/ec.rb                | 1 +
 lib/jwt/jwk/hmac.rb              | 1 +
 lib/jwt/jwk/key_base.rb          | 1 +
 lib/jwt/jwk/key_finder.rb        | 1 +
 lib/jwt/jwk/kid_as_key_digest.rb | 1 +
 lib/jwt/jwk/okp_rbnacl.rb        | 1 +
 lib/jwt/jwk/rsa.rb               | 1 +
 lib/jwt/jwk/set.rb               | 2 ++
 lib/jwt/version.rb               | 4 ++++
 25 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/.rubocop.yml b/.rubocop.yml
index ac4eb0e0..ad507d8b 100644
--- a/.rubocop.yml
+++ b/.rubocop.yml
@@ -6,9 +6,6 @@ AllCops:
     - 'gemfiles/*.gemfile'
     - 'vendor/**/*'
 
-Style/Documentation:
-  Enabled: false
-
 Metrics/AbcSize:
   Max: 25
 
diff --git a/lib/jwt/deprecations.rb b/lib/jwt/deprecations.rb
index 9f516a2d..34c73108 100644
--- a/lib/jwt/deprecations.rb
+++ b/lib/jwt/deprecations.rb
@@ -2,6 +2,7 @@
 
 module JWT
   # Deprecations module to handle deprecation warnings in the gem
+  # @api private
   module Deprecations
     class << self
       def context
diff --git a/lib/jwt/encoded_token.rb b/lib/jwt/encoded_token.rb
index 0264c51e..c0ed8b2e 100644
--- a/lib/jwt/encoded_token.rb
+++ b/lib/jwt/encoded_token.rb
@@ -111,7 +111,7 @@ def valid_signature?(algorithm:, key:)
     def decode_payload
       raise JWT::DecodeError, 'Encoded payload is empty' if encoded_payload == ''
 
-      if unecoded_payload?
+      if unencoded_payload?
         verify_claims!(crit: ['b64'])
         return parse_unencoded(encoded_payload)
       end
@@ -119,7 +119,7 @@ def decode_payload
       parse_and_decode(encoded_payload)
     end
 
-    def unecoded_payload?
+    def unencoded_payload?
       header['b64'] == false
     end
 
diff --git a/lib/jwt/json.rb b/lib/jwt/json.rb
index dffda08f..90ae4585 100644
--- a/lib/jwt/json.rb
+++ b/lib/jwt/json.rb
@@ -3,7 +3,7 @@
 require 'json'
 
 module JWT
-  # JSON wrapper
+  # @api private
   class JSON
     class << self
       def generate(data)
diff --git a/lib/jwt/jwa/ecdsa.rb b/lib/jwt/jwa/ecdsa.rb
index 580452f5..9876ecca 100644
--- a/lib/jwt/jwa/ecdsa.rb
+++ b/lib/jwt/jwa/ecdsa.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # ECDSA signing algorithm
     class Ecdsa
       include JWT::JWA::SigningAlgorithm
 
diff --git a/lib/jwt/jwa/eddsa.rb b/lib/jwt/jwa/eddsa.rb
index 824ef5e7..49f898ce 100644
--- a/lib/jwt/jwa/eddsa.rb
+++ b/lib/jwt/jwa/eddsa.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the EdDSA family of algorithms
     class Eddsa
       include JWT::JWA::SigningAlgorithm
 
diff --git a/lib/jwt/jwa/hmac.rb b/lib/jwt/jwa/hmac.rb
index be973306..e66d8ffd 100644
--- a/lib/jwt/jwa/hmac.rb
+++ b/lib/jwt/jwa/hmac.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the HMAC family of algorithms
     class Hmac
       include JWT::JWA::SigningAlgorithm
 
diff --git a/lib/jwt/jwa/hmac_rbnacl.rb b/lib/jwt/jwa/hmac_rbnacl.rb
index a48fb0d5..d553e387 100644
--- a/lib/jwt/jwa/hmac_rbnacl.rb
+++ b/lib/jwt/jwa/hmac_rbnacl.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the HMAC family of algorithms (using RbNaCl)
     class HmacRbNaCl
       include JWT::JWA::SigningAlgorithm
 
diff --git a/lib/jwt/jwa/hmac_rbnacl_fixed.rb b/lib/jwt/jwa/hmac_rbnacl_fixed.rb
index f697395d..8f26ccd6 100644
--- a/lib/jwt/jwa/hmac_rbnacl_fixed.rb
+++ b/lib/jwt/jwa/hmac_rbnacl_fixed.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the HMAC family of algorithms (using RbNaCl prior to a certain version)
     class HmacRbNaClFixed
       include JWT::JWA::SigningAlgorithm
 
diff --git a/lib/jwt/jwa/none.rb b/lib/jwt/jwa/none.rb
index ec2db20c..ddac9495 100644
--- a/lib/jwt/jwa/none.rb
+++ b/lib/jwt/jwa/none.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the none algorithm
     class None
       include JWT::JWA::SigningAlgorithm
 
diff --git a/lib/jwt/jwa/ps.rb b/lib/jwt/jwa/ps.rb
index 9bfb7058..547a5f9b 100644
--- a/lib/jwt/jwa/ps.rb
+++ b/lib/jwt/jwa/ps.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the RSASSA-PSS family of algorithms
     class Ps
       include JWT::JWA::SigningAlgorithm
 
diff --git a/lib/jwt/jwa/rsa.rb b/lib/jwt/jwa/rsa.rb
index d9169d42..d9ab925f 100644
--- a/lib/jwt/jwa/rsa.rb
+++ b/lib/jwt/jwa/rsa.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the RSA family of algorithms
     class Rsa
       include JWT::JWA::SigningAlgorithm
 
diff --git a/lib/jwt/jwa/signing_algorithm.rb b/lib/jwt/jwa/signing_algorithm.rb
index 65ae8469..8ddbf05a 100644
--- a/lib/jwt/jwa/signing_algorithm.rb
+++ b/lib/jwt/jwa/signing_algorithm.rb
@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 module JWT
+  # JSON Web Algorithms
   module JWA
+    # Base functionality for signing algorithms
     module SigningAlgorithm
+      # Class methods for the SigningAlgorithm module
       module ClassMethods
         def register_algorithm(algo)
           ::JWT::JWA.register_algorithm(algo)
diff --git a/lib/jwt/jwa/unsupported.rb b/lib/jwt/jwa/unsupported.rb
index 5d596101..beb4be1f 100644
--- a/lib/jwt/jwa/unsupported.rb
+++ b/lib/jwt/jwa/unsupported.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Represents an unsupported algorithm
     module Unsupported
       class << self
         include JWT::JWA::SigningAlgorithm
diff --git a/lib/jwt/jwa/wrapper.rb b/lib/jwt/jwa/wrapper.rb
index 46ff0e2f..41ba0fe6 100644
--- a/lib/jwt/jwa/wrapper.rb
+++ b/lib/jwt/jwa/wrapper.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # @api private
     class Wrapper
       include SigningAlgorithm
 
diff --git a/lib/jwt/jwk.rb b/lib/jwt/jwk.rb
index f6852bda..216351ea 100644
--- a/lib/jwt/jwk.rb
+++ b/lib/jwt/jwk.rb
@@ -4,6 +4,7 @@
 require_relative 'jwk/set'
 
 module JWT
+  # JSON Web Key (JWK)
   module JWK
     class << self
       def create_from(key, params = nil, options = {})
diff --git a/lib/jwt/jwk/ec.rb b/lib/jwt/jwk/ec.rb
index 40ccd2e4..567be48f 100644
--- a/lib/jwt/jwk/ec.rb
+++ b/lib/jwt/jwk/ec.rb
@@ -4,6 +4,7 @@
 
 module JWT
   module JWK
+    # JWK representation for Elliptic Curve (EC) keys
     class EC < KeyBase # rubocop:disable Metrics/ClassLength
       KTY    = 'EC'
       KTYS   = [KTY, OpenSSL::PKey::EC, JWT::JWK::EC].freeze
diff --git a/lib/jwt/jwk/hmac.rb b/lib/jwt/jwk/hmac.rb
index 5e243ccb..2eb88fca 100644
--- a/lib/jwt/jwk/hmac.rb
+++ b/lib/jwt/jwk/hmac.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # JWK for HMAC keys
     class HMAC < KeyBase
       KTY  = 'oct'
       KTYS = [KTY, String, JWT::JWK::HMAC].freeze
diff --git a/lib/jwt/jwk/key_base.rb b/lib/jwt/jwk/key_base.rb
index 2c80d760..4962d112 100644
--- a/lib/jwt/jwk/key_base.rb
+++ b/lib/jwt/jwk/key_base.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # Base for JWK implementations
     class KeyBase
       def self.inherited(klass)
         super
diff --git a/lib/jwt/jwk/key_finder.rb b/lib/jwt/jwk/key_finder.rb
index fd053416..5498800c 100644
--- a/lib/jwt/jwk/key_finder.rb
+++ b/lib/jwt/jwk/key_finder.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # @api private
     class KeyFinder
       def initialize(options)
         @allow_nil_kid = options[:allow_nil_kid]
diff --git a/lib/jwt/jwk/kid_as_key_digest.rb b/lib/jwt/jwk/kid_as_key_digest.rb
index e526b786..08a1d2a7 100644
--- a/lib/jwt/jwk/kid_as_key_digest.rb
+++ b/lib/jwt/jwk/kid_as_key_digest.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # @api private
     class KidAsKeyDigest
       def initialize(jwk)
         @jwk = jwk
diff --git a/lib/jwt/jwk/okp_rbnacl.rb b/lib/jwt/jwk/okp_rbnacl.rb
index 76cfdf23..eae5772f 100644
--- a/lib/jwt/jwk/okp_rbnacl.rb
+++ b/lib/jwt/jwk/okp_rbnacl.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # JSON Web Key (JWK) representation for Ed25519 keys
     class OKPRbNaCl < KeyBase
       KTY  = 'OKP'
       KTYS = [KTY, JWT::JWK::OKPRbNaCl, RbNaCl::Signatures::Ed25519::SigningKey, RbNaCl::Signatures::Ed25519::VerifyKey].freeze
diff --git a/lib/jwt/jwk/rsa.rb b/lib/jwt/jwk/rsa.rb
index 5d8012e2..44044075 100644
--- a/lib/jwt/jwk/rsa.rb
+++ b/lib/jwt/jwk/rsa.rb
@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # JSON Web Key (JWK) representation of a RSA key
     class RSA < KeyBase # rubocop:disable Metrics/ClassLength
       BINARY = 2
       KTY    = 'RSA'
diff --git a/lib/jwt/jwk/set.rb b/lib/jwt/jwk/set.rb
index 72e5f663..6f93e56e 100644
--- a/lib/jwt/jwk/set.rb
+++ b/lib/jwt/jwk/set.rb
@@ -4,6 +4,8 @@
 
 module JWT
   module JWK
+    # JSON Web Key Set (JWKS) representation
+    # https://tools.ietf.org/html/rfc7517
     class Set
       include Enumerable
       extend Forwardable
diff --git a/lib/jwt/version.rb b/lib/jwt/version.rb
index 71ebdff7..35fe141c 100644
--- a/lib/jwt/version.rb
+++ b/lib/jwt/version.rb
@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# JSON Web Token implementation
+#
+# Should be up to date with the latest spec:
+# https://tools.ietf.org/html/rfc7519
 module JWT
   # Returns the gem version of the JWT library.
   #