sober_swag 0.19.0 → 0.20.0

data/lib/sober_swag/parser.rb

@@ -1,13 +1,19 @@
 module SoberSwag
   ##
   # Parses a *Dry-Types Schema* into a set of nodes we can use to compile.
-  # This is mostly because the vistior pattern sucks and catamorphisms are nice.
+  # This is mostly because the visitor pattern sucks and catamorphisms are nice.
+  #
+  # Do not use this class directly, as it is not part of the public api.
+  # Instead, use classes from the {SoberSwag::Compiler} namespace.
   class Parser
     def initialize(node)
       @node = node
       @found = Set.new
     end
 
+    ##
+    # Compile to one of our internal nodes.
+    # @return [SoberSwag::Nodes::Base] the node that describes this type.
     def to_syntax # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
       case @node
       when Dry::Types::Default

data/lib/sober_swag/serializer/array.rb

@@ -1,30 +1,54 @@
 module SoberSwag
   module Serializer
     ##
-    # Make a serialize of arrays out of a serializer of the elements
+    # Transform a serializer that works on elements to one that works on Arrays
     class Array < Base
+      ##
+      # Make an array serializer out of another serializer.
+      # @param element_serializer [SoberSwag::Serializer::Base] the serializer to use for each element.
       def initialize(element_serializer)
         @element_serializer = element_serializer
       end
 
+      ##
+      # The serializer that will be used for each element in the array.
+      #
+      # @return [SoberSwag::Serializer::Base]
+      attr_reader :element_serializer
+
+      ##
+      # Delegates to {#element_serializer}
       def lazy_type?
         @element_serializer.lazy_type?
       end
 
+      ##
+      # Delegates to {#element_serializer}, wrapped in an array
       def lazy_type
         SoberSwag::Types::Array.of(@element_serializer.lazy_type)
       end
 
+      ##
+      # Delegates to {#element_serializer}
       def finalize_lazy_type!
         @element_serializer.finalize_lazy_type!
       end
 
-      attr_reader :element_serializer
-
+      ##
+      # Serialize an array of objects that can be serialized with {#element_serializer}
+      # by calling `element_serializer.serialize` for each item in this array.
+      #
+      # Note: since ruby is duck-typed, anything that responds to the `#map` method from
+      # [Enumerable](https://ruby-doc.org/core-3.0.0/Enumerable.html) should work!
+      #
+      # @param object [Array<Object>,#map] collection of objects to serialize
+      # @return [Array<Object>] JSON-compatible array
       def serialize(object, options = {})
         object.map { |a| element_serializer.serialize(a, options) }
       end
 
+      ##
+      # The type of items returned from {#serialize}
       def type
         SoberSwag::Types::Array.of(element_serializer.type)
       end

data/lib/sober_swag/serializer/base.rb

@@ -1,34 +1,91 @@
 module SoberSwag
   module Serializer
     ##
-    # Base interface class that all other serializers are subclasses of.
-    # This also defines methods as stubs, which is sort of bad ruby style, but makes documentation
-    # easier to generate.
+    # Base class for everything that provides serialization functionality in SoberSwag.
+    # SoberSwag serializers transform Ruby types into JSON types, with some associated *schema*.
+    # This schema is then used in the generated OpenAPI V3 documentation.
     class Base
       ##
       # Return a new serializer that is an *array* of elements of this serializer.
+      # This serializer will take in an array, and use `self` to serialize every element.
+      #
+      # @return [SoberSwag::Serializer::Array]
       def array
         SoberSwag::Serializer::Array.new(self)
       end
 
       ##
-      # Returns a serializer that will pass `nil` values on unscathed
+      # Returns a serializer that will pass `nil` values on unscathed.
+      # That means that if you try to serialize `nil` with it, it will result in a JSON `null`.
+      # @return [SoberSwag::Serializer::Optional]
       def optional
         SoberSwag::Serializer::Optional.new(self)
       end
 
       alias nilable optional
 
+      ##
+      # Add metadata onto the *type* of a serializer.
+      # Note that this *returns a new serializer with metadata added* and does not perform mutation.
+      # @param hash [Hash] the metadata to set.
+      # @return [SoberSwag::Serializer::Meta] a serializer with metadata added
+      def meta(hash)
+        SoberSwag::Serializer::Meta.new(self, hash)
+      end
+
+      ##
+      # Get a new serializer that will first run the given block before serializing an object.
+      # For example, if you have a serializer for strings called `StringSerializer`,
+      # and you want to serialize `Date` objects via encoding them to a standardized string format,
+      # you can use:
+      #
+      # ```
+      #   DateSerializer = StringSerializer.via_map do |date|
+      #     date.strftime('%Y-%m-%d')
+      #   end
+      # ```
+      #
+      # @yieldparam [Object] the object before serialization
+      # @yieldreturn [Object] a transformed object, that will
+      #   be passed to {#serialize}
+      # @return [SoberSwag::Serializer::Mapped] the new serializer
+      def via_map(&block)
+        SoberSwag::Serializer::Mapped.new(self, block)
+      end
+
       ##
       # Is this type lazily defined?
       #
-      # Used for mutual recursion.
+      # If we have two serializers that are *mutually recursive*, we need to do some "fun" magic to make that work.
+      # This comes up in a case like:
+      #
+      # ```ruby
+      #   SchoolClass = SoberSwag::OutputObject.define do
+      #     field :name, primitive(:String)
+      #     view :detail do
+      #       field :students, -> { Student.view(:base) }
+      #     end
+      #   end
+      #
+      #   Student = SoberSwag::OutputObject.define do
+      #     field :name, primitive(:String)
+      #     view :detail do
+      #       field :classes, -> { SchoolClass.view(:base) }
+      #     end
+      #   end
+      # ```
+      #
+      # This would result in an infinite loop if we tried to define the type struct the easy way.
+      # So, we instead use mutation to achieve "laziness."
       def lazy_type?
         false
       end
 
       ##
       # The lazy version of this type, for mutual recursion.
+      # @see #lazy_type? for why this is needed
+      #
+      # Once you call {#finalize_lazy_type!}, the type will be "fleshed out," and can be actually used.
       def lazy_type
         type
       end
@@ -43,43 +100,36 @@ module SoberSwag
 
       ##
       # Serialize an object.
+      # @abstract
       def serialize(_object, _options = {})
         raise ArgumentError, 'not implemented!'
       end
 
       ##
       # Get the type that we serialize to.
+      # @abstract
       def type
         raise ArgumentError, 'not implemented!'
       end
 
       ##
-      # Add metadata onto the *type* of a serializer.
-      def meta(hash)
-        SoberSwag::Serializer::Meta.new(self, hash)
-      end
-
-      ##
-      # If I am a serializer for type 'a', and you give me a way to turn 'a's into 'b's,
-      # I can give you a serializer for type 'b' by running the funciton you gave.
-      # For example, if I am a serializer for {String}, and you know how to turn
-      # an {Int} into a {String}, I can now serialize {Int}s (by turning them into a string).
+      # Returns self.
       #
-      # Note that the *declared* type of this is *not* changed: from a user's perspective,
-      # they see a "string"
-      def via_map(&block)
-        SoberSwag::Serializer::Mapped.new(self, block)
-      end
-
-      ##
-      # Serializer lets you get a serializer from things that might be classes
-      # because of the blueprint naming hack.
+      # This exists due to a hack.
       def serializer
         self
       end
 
       ##
-      # Get the type name of this to be used externally, or set it if an argument is provided
+      # @overload identifier()
+      #   Returns the external identifier, used to uniquely identify this object within
+      #   the schemas section of an OpenAPI v3 document.
+      #   @return [String] the identifier.
+      # @overload identifier(arg)
+      #   Sets the external identifier to use to uniquely identify
+      #   this object within the schemas section of an OpenAPI v3 document.
+      #   @param arg [String] the identifier to use
+      #   @return [String] the identifer set
       def identifier(arg = nil)
         @identifier = arg if arg
         @identifier

data/lib/sober_swag/serializer/conditional.rb

@@ -10,19 +10,49 @@ module SoberSwag
     # This is a very weird, not-very-Ruby-like abstraction, *upon which* we can build abstractions that are actually use for users.
     # It lets you build abstractions like "Use this serializer if a type has this class, otherwise use this other one."
     # When composed together, you can make arbitrary decision trees.
+    #
+    # This class is heavily inspired by
+    # the [Decideable](https://hackage.haskell.org/package/contravariant-1.5.3/docs/Data-Functor-Contravariant-Divisible.html#t:Decidable)
+    # typeclass from Haskell.
     class Conditional < Base
       ##
       # Error thrown when a chooser proc returns a non left-or-right value.
       class BadChoiceError < Error; end
 
+      ##
+      # Create a new conditional serializer, from a "chooser" proc, a "left" serializer, and a "right" serializer.
+      #
+      # @param chooser [Proc,Lambda] the proc that chooses which "side" to use
+      # @param left [SoberSwag::Serializer::Base] a serializer for the "left" side
+      # @param right [SoberSwag::Serializer::Base] a serializer for the "right" side
       def initialize(chooser, left, right)
         @chooser = chooser
         @left = left
         @right = right
       end
 
-      attr_reader :chooser, :left, :right
+      ##
+      # @return [Proc,Lambda] the "chooser" proc.
+      attr_reader :chooser
+
+      ##
+      # @return [SoberSwag::Serializer::Base] the serializer to use if the "chooser" proc chooses `:right`.
+      #   Also called the "left-side serializer."
+      attr_reader :left
 
+      ##
+      # @return [SoberSwag::Serializer::Base] the serializer to use if the "chooser" proc chooses `:right`.
+      #   Also called the "right-side serializer."
+      attr_reader :right
+
+      ##
+      # First, call {#chooser} with `object` and `options` to see what serializer to use, and *what* to serialize.
+      # Then, if it returns `[:left, val]`, use {#left} to serialize `val`.
+      # Otherwise, if it returns `[:right, val]`, use {#right} to serialize `val`.
+      # If it returns neither, throw {BadChoiceError}.
+      #
+      # @raise [BadChoiceError] if {#chooser} did not choose what side to use
+      # @return [Hash] a JSON-compatible object
       def serialize(object, options = {})
         tag, val = chooser.call(object, options)
         case tag
@@ -58,6 +88,8 @@ module SoberSwag
         left.lazy_type? || right.lazy_type?
       end
 
+      ##
+      # Finalize both {#left} and {#right}
       def finalize_lazy_type!
         [left, right].each(&:finalize_lazy_type!)
       end

data/lib/sober_swag/serializer/field_list.rb

@@ -1,13 +1,18 @@
 module SoberSwag
   module Serializer
     ##
-    # Extract out a hash from a list of
-    # name/serializer pairs.
+    # Extracts a JSON hash from a list of {SoberSwag::OutputObject::Field} structs.
     class FieldList < Base
+      ##
+      # Create a new field-list serializer.
+      #
+      # @param field_list [Array<SoberSwag::OutputObject::Field>] descriptions of each field
       def initialize(field_list)
         @field_list = field_list
       end
 
+      ##
+      # @return [Array<SoberSwag::OutputObject::Field>] the list of fields to use.
       attr_reader :field_list
 
       ##
@@ -16,16 +21,27 @@ module SoberSwag
         SoberSwag::Serializer.Primitive(SoberSwag::Types.const_get(symbol))
       end
 
+      ##
+      # Serialize an object to a JSON hash by using each field in the list.
+      # @param object [Object] object to serialize
+      # @param options [Hash] arbitrary options
+      # @return [Hash] serialized object.
       def serialize(object, options = {})
         field_list.map { |field|
           [field.name, field.serializer.serialize(object, options)]
         }.to_h
       end
 
+      ##
+      # Construct a Dry::Struct from the fields given.
+      # This Struct will be swagger-able.
+      # @return [Dry::Struct]
       def type
         @type ||= make_struct_type!
       end
 
+      ##
+      # These types are always constructed lazily.
       def lazy_type?
         true
       end

data/lib/sober_swag/serializer/mapped.rb

@@ -3,12 +3,21 @@ module SoberSwag
     ##
     # A new serializer by mapping over the serialization function
     class Mapped < Base
+      ##
+      # Create a new mapped serializer.
+      # @param base [SoberSwag::Serializer::Base] a serializer to use after mapping
+      # @param map_f [Proc,Lambda] a mapping function to use before serialization
       def initialize(base, map_f)
         @base = base
         @map_f = map_f
       end
 
-      attr_reader :base, :map_f
+      ##
+      # @return [SoberSwag::Serializer::Base] serializer to use after mapping
+      attr_reader :base
+      ##
+      # @return [Proc, Lambda, #call] function to use before serialization
+      attr_reader :map_f
 
       def serialize(object, options = {})
         @base.serialize(@map_f.call(object), options)

data/lib/sober_swag/serializer/optional.rb

@@ -5,11 +5,20 @@ module SoberSwag
     # this can be used to make a serializer of type 'A | nil'.
     #
     # Or, put another way, makes serializers not crash on nil values.
+    # If {#serialize} is passed nil, it will return `nil` immediately, and not
+    # try to call the serializer of {#inner}.
     class Optional < Base
+      ##
+      # An error thrown when trying to nest optional serializers.
+      class NestedOptionalError < Error; end
+      ##
+      # @param inner [SoberSwag::Serializer::Base] the serializer to use for non-nil values
       def initialize(inner)
         @inner = inner
       end
 
+      ##
+      # @return [SoberSwag::Serializer::Base] the serializer to use for non-nil values.
       attr_reader :inner
 
       def lazy_type?
@@ -24,6 +33,9 @@ module SoberSwag
         @inner.finalize_lazy_type!
       end
 
+      ##
+      # If `object` is nil, return `nil`.
+      # Otherwise, call `inner.serialize(object, options)`.
       def serialize(object, options = {})
         if object.nil?
           object
@@ -36,8 +48,13 @@ module SoberSwag
         inner.type.optional
       end
 
+      ##
+      # Since nesting optional types is bad, this will always raise an ArgumentError
+      #
+      # @raise [NestedOptionalError] always
+      # @return [void] nothing, always raises.
       def optional(*)
-        raise ArgumentError, 'no nesting optionals please'
+        raise NestedOptionalError, 'no nesting optionals please'
       end
     end
   end

data/lib/sober_swag/serializer/primitive.rb

@@ -4,6 +4,9 @@ module SoberSwag
     # A class that does *no* serialization: you give it a type,
     # and it will pass any serialized input on verbatim.
     class Primitive < Base
+      ##
+      # Construct a primitive serializer with a description of the type it serializes to.
+      # @param type [Class] a swagger-able type
       def initialize(type)
         @type = type
       end

data/lib/sober_swag/server.rb

@@ -21,7 +21,7 @@ module SoberSwag
     # Start up.
     #
     # @param controller_proc [Proc] a proc that, when called, gives a list of {SoberSwag::Controller}s to document
-    # @param cache [Bool | Proc] if we should cache our defintions (default false)
+    # @param cache [Bool | Proc] if we should cache our definitions (default false)
     # @param redoc_version [String] what version of the redoc library to use to display UI (default 'next', the latest version).
     def initialize(
       controller_proc: RAILS_CONTROLLER_PROC,
@@ -60,6 +60,8 @@ module SoberSwag
       </html>
     HTML
 
+    ##
+    # Standard Rack call method.
     def call(env)
       req = Rack::Request.new(env)
       if req.path_info&.match?(/json/si) || req.get_header('Accept')&.match?(/json/si)
@@ -69,6 +71,8 @@ module SoberSwag
       end
     end
 
+    private
+
     def generate_json_string
       if cache?
         @json_string ||= JSON.dump(generate_swagger)