stripe gem comments for Will

modules_explanation.rb

# stripe-ruby gem class example
# https://github.com/stripe/stripe-ruby/blob/master/lib/stripe/resources/checkout/session.rb

# Top level module - typically the gem name
# Reference: https://github.com/stripe/stripe-ruby/blob/master/lib/stripe.rb
# This file will either be directly required there or one of the other files
# it requires will require this.
module Stripe
  # Stripes API is so large they had enough of a reason
  # to separate the resource concern further. Typically
  # this pattern is used throughout the project, even if
  # it doesnt make sense for everything. Ex: Checkout only
  # has one subclass, Session, but keeping it organized
  # like this vs naming this Strip::CheckoutSession gives
  # more flexibility long term to add more resources.
  module Checkout
    # The class is the last layer of abstraction.
    # This is the session class for the checkout
    # resource under the stripe namespace.
    #
    # It is also _inheiriting_ the methods of APIResource
    # https://github.com/stripe/stripe-ruby/blob/master/lib/stripe/api_resource.rb
    # This means it can access or override all of the _public_ methods in
    # Stripe::ApiResource, which in turn inheirits classes from StripeObject.
    # This is a way to cleanly abstract common behavior!
    class Session < APIResource
      # We are extending the methods in the following
      # API ops. We can guess without looking that
      # the Checkout Session API endpoint allows for creating
      # new sessions (POST(create controller method)), listing
      # sessions (GET(index controller method)), and it has operations
      # for nested resources so we know one of the objects we use to
      # create the session is an object
      extend Stripe::APIOperations::Create
      extend Stripe::APIOperations::List
      extend Stripe::APIOperations::NestedResource
      # Include vs Extend https://www.geeksforgeeks.org/include-v-s-extend-in-ruby/

      # Overrides the inheirited object name
      # https://github.com/stripe/stripe-ruby/blob/master/lib/stripe/object_types.rb
      OBJECT_NAME = "checkout.session"

      # https://github.com/stripe/stripe-ruby/blob/8710fcaddc2693e073259799ffbff11ba349226d/lib/stripe/api_operations/nested_resource.rb#L13
      # Operations for the nested resource: https://github.com/stripe/stripe-ruby/blob/master/lib/stripe/resources/line_item.rb
      nested_resource_class_methods :line_item, operations: %i[list]
    end
  end
end

# ButWhy

# If you need some more help, this should seal the deal:
#
#
# ./lib/
# ├── stripe
# │   ├── resources
# │   │   ├── checkout
# │   │   │   └── session.rb
# └── stripe.rb

# This is the directory structure of the gem with all the other files removed. Generally
# each module means you descend into another folder. Checkout a rails api controller for
# ex `rails new foo --api` i think. Althogh this isnt required, its best practice. Otherwise
# youd likely see:

# Stripe::Checkout::Session < APIResource

# vs

# module Stripe
#   module Checkout
#     class Session < APIResource
#
# Just pattern!