Adds documentations for IncludedSchemaGenerator

lib/schemable/included_schema_generator.rb

@@ -1,13 +1,40 @@
 module Schemable
+  # The IncludedSchemaGenerator class is responsible for generating the 'included' part of a JSON:API compliant response.
+  # This class generates schemas for related resources that should be included in the response.
+  #
+  # @see Schemable
   class IncludedSchemaGenerator
     attr_reader :model_definition, :schema_modifier, :relationships
 
+    # Initializes a new IncludedSchemaGenerator instance.
+    #
+    # @param model_definition [ModelDefinition] The model definition to generate the schema for.
+    #
+    # @example
+    #   generator = IncludedSchemaGenerator.new(model_definition)
     def initialize(model_definition)
       @model_definition = model_definition
       @schema_modifier = SchemaModifier.new
       @relationships = @model_definition.relationships
     end
 
+    # Generates the 'included' part of the JSON:API response.
+    # It iterates over each relationship type (belongs_to, has_many) and for each relationship,
+    # it prepares a schema. If the 'expand' option is true, it also includes the relationships of the related resource in the schema.
+    # In that case, the 'addition_to_included' relationships are also included in the schema unless they are excluded from expansion.
+    #
+    # @param expand [Boolean] Whether to include the relationships of the related resource in the schema.
+    # @param relationships_to_exclude_from_expansion [Array] The relationships to exclude from the schema.
+    #
+    # @note Make sure to provide the names correctly in string format and pluralize them if necessary.
+    #       For example, if you have a relationship named 'applicant', and an applicant has association
+    #       named 'identity', you should provide 'identities' as the names of the relationship to exclude from expansion.
+    #       In this case, the included schema of the applicant will not include the identity relationship.
+    #
+    # @example
+    #   schema = generator.generate(expand: true, relationships_to_exclude_from_expansion: ['some_relationship'])
+    #
+    # @return [Hash] The generated schema.
     def generate(expand: false, relationships_to_exclude_from_expansion: [])
       return {} if @relationships.blank?
       return {} if @relationships == { belongs_to: {}, has_many: {} }
@@ -52,6 +79,17 @@ module Schemable
       schema
     end
 
+    # Prepares the schema for a related resource to be included in the response.
+    # It generates the attribute and relationship schemas for the related resource and combines them into a single schema.
+    #
+    # @param model_definition [ModelDefinition] The model definition of the related resource.
+    # @param expand [Boolean] Whether to include the relationships of the related resource in the schema.
+    # @param relationships_to_exclude_from_expansion [Array] The relationships to exclude from the schema.
+    #
+    # @example
+    #   included_schema = generator.prepare_schema_for_included(related_model_definition, expand: true, relationships_to_exclude_from_expansion: ['some_relationship'])
+    #
+    # @return [Hash] The generated schema for the related resource.
     def prepare_schema_for_included(model_definition, expand: false, relationships_to_exclude_from_expansion: [])
       attributes_schema = AttributeSchemaGenerator.new(model_definition).generate
       relationships_schema = RelationshipSchemaGenerator.new(model_definition).generate(relationships_to_exclude_from_expansion:, expand:)