Add some documentation

.rubocop_todo.yml

@@ -1,17 +1,16 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-05-30 18:44:57 UTC using RuboCop version 1.63.4.
+# on 2024-06-05 00:21:36 UTC using RuboCop version 1.63.4.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 6
+# Offense count: 2
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
-    - "lib/transmutation/class_attributes.rb"
-    - "lib/transmutation/collection_serializer.rb"
-    - "lib/transmutation/serialization.rb"
-    - "lib/transmutation/serializer.rb"
-    - "lib/transmutation/string_refinements.rb"
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/transmutation/serialization.rb'
+    - 'lib/transmutation/serialization/rendering.rb'

lib/transmutation.rb

@@ -4,6 +4,43 @@
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
+# A performant and expressive solution for serializing Ruby objects into JSON, with a touch of opinionated "magic" ✨.
+#
+# @example Basic usage
+#   # Define a data class.
+#   class User
+#     attr_reader :name, :email
+#
+#     def initialize(name:, email:)
+#       @name = name
+#       @email = email
+#     end
+#   end
+#
+#   # Define a serializer.
+#   class UserSerializer < Transmutation::Serializer
+#     attribute :name
+#   end
+#
+#   # Create an instance of the data class.
+#   user = User.new(name: "John", email: "[email protected]")
+#
+#   # Serialize the data class instance.
+#   UserSerializer.new(user).to_json # => "{\"name\":\"John\"}"
+#
+# @example Within a Rails controller
+#   class UsersController < ApplicationController
+#     include Transmutation::Serialization
+#
+#     def show
+#       user = User.find(params[:id])
+#
+#       # Automatically lookup the UserSerializer
+#       # Serialize the data class instance using the UserSerializer
+#       # Render the result as JSON to the client
+#       render json: user # => "{\"name\":\"John\"}"
+#     end
+#   end
 module Transmutation
   class Error < StandardError; end
 end

lib/transmutation/class_attributes.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Transmutation
+  # @api private
   module ClassAttributes
     def class_attribute(
       *names,

lib/transmutation/serializer.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module Transmutation
+  # Base class for your serializers.
+  #
+  # @example Basic usage
+  #   class UserSerializer < Transmutation::Serializer
+  #     attributes :first_name, :last_name
+  #
+  #     attribute :full_name do
+  #       "#{object.first_name} #{object.last_name}".strip
+  #     end
+  #   end
   class Serializer
     extend ClassAttributes
 
@@ -18,13 +28,35 @@ def as_json(_options = {})
       end
     end
 
-    def self.attribute(attr_name, &block)
-      attributes_config[attr_name] = { block: block }
+    # Define an attribute to be serialized
+    #
+    # @param attribute_name [Symbol] The name of the attribute to serialize
+    # @param block [Proc] The block to call to get the value of the attribute.
+    #   The block is called in the context of the serializer instance.
+    #
+    # @example
+    #   class UserSerializer < Transmutation::Serializer
+    #     attribute :first_name
+    #
+    #     attribute :full_name do
+    #       "#{object.first_name} #{object.last_name}".strip
+    #     end
+    #   end
+    def self.attribute(attribute_name, &block)
+      attributes_config[attribute_name] = { block: block }
     end
 
-    def self.attributes(*attr_name)
-      attr_name.each do |name|
-        attribute(name)
+    # Shorthand for defining multiple attributes
+    #
+    # @param attribute_names [Array<Symbol>] The names of the attributes to serialize
+    #
+    # @example
+    #   class UserSerializer < Transmutation::Serializer
+    #     attributes :first_name, :last_name
+    #   end
+    def self.attributes(*attribute_names)
+      attribute_names.each do |attr_name|
+        attribute(attr_name)
       end
     end