class_methods.rb in rom-sql-0.5.0

- old
+ new

@@ -1,9 +1,15 @@
 module ROM
   module SQL
     class Relation < ROM::Relation
+      # Class DSL for SQL relations
+      #
+      # @api private
       module ClassMethods
+        # Set up model and association ivars for descendant class
+        #
+        # @api private
         def inherited(klass)
           klass.class_eval do
             class << self
               attr_reader :model, :associations
             end
@@ -11,23 +17,86 @@
           klass.instance_variable_set('@model', Class.new(Sequel::Model))
           klass.instance_variable_set('@associations', [])
           super
         end
 
+        # Set up a one-to-many association
+        #
+        # @example
+        #   class Users < ROM::Relation[:sql]
+        #     one_to_many :tasks, key: :user_id
+        #
+        #     def with_tasks
+        #       association_join(:tasks)
+        #     end
+        #   end
+        #
+        # @param [Symbol] name The name of the association
+        # @param [Hash] options The options hash
+        # @option options [Symbol] :key Name of the key to join on
+        # @option options [Hash] :on Additional conditions for join
+        # @option options [Hash] :conditions Additional conditions for WHERE
+        #
+        # @api public
         def one_to_many(name, options)
           associations << [__method__, name, { relation: name }.merge(options)]
         end
 
+        # Set up a many-to-many association
+        #
+        # @example
+        #   class Tasks < ROM::Relation[:sql]
+        #     many_to_many :tags,
+        #       join_table: :task_tags,
+        #       left_key: :task_id,
+        #       right_key: :tag_id,
+        #
+        #     def with_tags
+        #       association_join(:tags)
+        #     end
+        #   end
+        #
+        # @param [Symbol] name The name of the association
+        # @param [Hash] options The options hash
+        # @option options [Symbol] :join_table Name of the join table
+        # @option options [Hash] :left_key Name of the left join key
+        # @option options [Hash] :right_key Name of the right join key
+        # @option options [Hash] :on Additional conditions for join
+        # @option options [Hash] :conditions Additional conditions for WHERE
+        #
+        # @api public
         def many_to_many(name, options = {})
           associations << [__method__, name, { relation: name }.merge(options)]
         end
 
+        # Set up a many-to-one association
+        #
+        # @example
+        #   class Tasks < ROM::Relation[:sql]
+        #     many_to_one :users, key: :user_id
+        #
+        #     def with_users
+        #       association_join(:users)
+        #     end
+        #   end
+        #
+        # @param [Symbol] name The name of the association
+        # @param [Hash] options The options hash
+        # @option options [Symbol] :join_table Name of the join table
+        # @option options [Hash] :key Name of the join key
+        # @option options [Hash] :on Additional conditions for join
+        # @option options [Hash] :conditions Additional conditions for WHERE
+        #
+        # @api public
         def many_to_one(name, options = {})
           relation_name = Inflector.pluralize(name).to_sym
           new_options = options.merge(relation: relation_name)
           associations << [__method__, name, new_options]
         end
 
+        # Finalize the relation by setting up its associations (if any)
+        #
+        # @api private
         def finalize(relations, relation)
           model.set_dataset(relation.dataset)
           model.dataset.naked!
 
           associations.each do |*args, assoc_opts|