Documentation effort

lib/correlate.rb

@@ -1,4 +1,60 @@
-
+# = Correlate
+#
+# Correlate is an experiment in loosely defining relationships between documents
+# stored in CouchDB using CouchRest's ExtendedDocument, as well as relationships
+# between these documents and ActiveRecord models.
+#
+# == Overview
+#
+# Relationships are defined as an array of hashes, each hash containing a +rel+
+# and +href+ key. This is modelled on HTML's success in loosely defining
+# relationships between different documents.
+#
+# A sample might look like this:
+#
+#
+#  {
+#    ...
+#    "links" : [
+#     { "rel" : "another_doc", "href" : "<uuid>" },
+#     { "rel" : "important", "href" : "<uuid>" }
+#     ...
+#    ]
+#    ...
+#  }
+#
+# == Using correlate
+#
+# Correlate presents itself as a mixin for CouchRest::ExtendedDocument classes,
+# as well as ActiveRecord models.
+#
+# === Using with CouchRest::ExtendedDocument
+#
+#   class SomeDocument < CouchRest::ExtendedDocument
+#     include Correlate
+#
+#     related_to do
+#       some :other_documents, :class => 'OtherDocument', :rel => 'other_document'
+#       a :parent_document, :class => 'ParentDocument'
+#     end
+#   end
+#
+#
+# === Using with ActiveRecord::Base
+#
+#   class Model < ActiveRecord::Base
+#     include Correlate
+#
+#     related_to do
+#       some :documents, :class => 'Document', :rel => 'model'
+#     end
+#   end
+#
+# When correlating ActiveRecord models with CouchRest documents, it is required
+# that the 'reverse correlation' is specified in the CouchRest class.
+#
+# @see Correlate::Relationships::CouchRest
+# @see Correlate::Relationships::ActiveRecord
 module Correlate
 
   VERSION = '0.0.0'
@@ -14,10 +70,17 @@ def self.included( base )
 
   module ClassMethods
 
+    # Depending on the containing class, this method configures either a
+    # Correlate::Relationships::CouchRest or a
+    # Correlate::Relationships::ActiveRecord.
+    #
+    # @see Correlate::Relationships::CouchRest
+    # @see Correlate::Relationships::ActiveRecord
     def related_to( &block )
       Correlate::Relationships.configure!( self, &block )
     end
 
+    # @private
     def correlations
       @correlations ||= []
     end

lib/correlate/relationships/couchrest.rb

@@ -1,5 +1,23 @@
 module Correlate
   module Relationships
+
+    # Configure relationships between CouchRest::ExtendedDocument classes, as
+    # well as between CouchRest::ExtendedDocument & ActiveRecord::Base classes.
+    #
+    # Using this correlation in a CouchRest::ExtendedDocument creates a +links+
+    # property that is used for storing the correlations between this document
+    # and others.
+    #
+    # It also creates a +rel+ view for the class that emits two keys: +rel+ &
+    # +href+, which is used for bulk lookups and loading of documents.
+    #
+    # == Notes
+    #
+    # To use the validations provided by Correlate you need to include
+    # +CouchRest::Validation+ into your classes.
+    #
+    # @see #a
+    # @see #some
     class CouchRest
 
       class << self
@@ -29,12 +47,36 @@ def initialize( klass )
         @klass = klass
       end
 
-      def some( *args )
-        name = args.shift
-        opts = args.empty? ? {} : args.last
-        opts[:source] = @klass
-
-        @klass.correlations << Correlate::Relationships.build_correlation( name, :some, opts )
+      # Specify that this document will have multiple documents of said relationship.
+      #
+      # @example Defining correlations and using them
+      #   class SomeDocument < CouchRest::ExtendedDocument
+      #     include Correlate
+      #
+      #     related_to do
+      #       some :other_documents, :class => 'OtherDocument, :rel => 'other_document'
+      #     end
+      #   end
+      #
+      #   doc = SomeDocument.new
+      #   doc.other_documents # => []
+      #
+      #   other_doc = OtherDocument.get( '885387e892e63f4b6d31dbc877533099' )
+      #   doc.other_documents << other_doc
+      #
+      #   doc.other_documents # => [ <OtherDocument#12121212> ]
+      #
+      # @param [Symbol] name of the relationship
+      # @param [Hash] options for the relationship
+      # @option options [String] :class the class of the related document/model
+      # @option options [String] :rel the value of the +rel+ key in the related hash
+      # @option options [Fixnum] :requires (nil) a number of documents required
+      # @option options [Symbol] :id_method (:id) name of a method use to retrieve the 'foreign key' value from documents added to the relationship
+      # @option options [Symbol] :load_via (:get/:find) name of the class method used to retreive related documents (defaults to :get for CouchRest::ExtendedDocument, :find for ActiveRecord::Base)
+      def some( name, options = {} )
+        options[:source] = @klass
+
+        @klass.correlations << Correlate::Relationships.build_correlation( name, :some, options )
 
         @klass.class_eval <<-EOF, __FILE__, __LINE__
           def #{name}( raw = false )
@@ -49,12 +91,36 @@ def #{name}( raw = false )
         EOF
       end
 
-      def a( *args )
-        name = args.shift
-        opts = args.empty? ? {} : args.last
-        opts[:source] = @klass
-
-        @klass.correlations << Correlate::Relationships.build_correlation( name, :a, opts )
+      # Specify that this document will have a single document of said relationship.
+      #
+      # @example Defining correlations and using them
+      #   class OtherDocument < CouchRest::ExtendedDocument
+      #     include Correlate
+      #
+      #     related_to do
+      #       a :some_document, :class => 'SomeDocument'
+      #     end
+      #   end
+      #
+      #   doc = OtherDocument.new
+      #   doc.some_document # => nil
+      #
+      #   some_doc = SomeDocument.get( '885387e892e63f4b6d31dbc877533099' )
+      #   doc.some_document = some_doc
+      #
+      #   doc.some_document # => [ <SomeDocument#12121212> ]
+      #
+      # @param [Symbol] name of the relationship
+      # @param [Hash] options for the relationship
+      # @option options [String] :class the class of the related document/model
+      # @option options [String] :rel (name) the value of the +rel+ key in the related hash
+      # @option options [Fixnum] :required (false) whether required or not
+      # @option options [Symbol] :id_method (:id) name of a method use to retrieve the 'foreign key' value from documents added to the relationship
+      # @option options [Symbol] :load_via (:get/:find) name of the class method used to retreive related documents (defaults to :get for CouchRest::ExtendedDocument, :find for ActiveRecord::Base)
+      def a( name, options = {} )
+        options[:source] = @klass
+
+        @klass.correlations << Correlate::Relationships.build_correlation( name, :a, options )
 
         @klass.class_eval <<-EOF, __FILE__, __LINE__
           def #{name}=( object )
@@ -72,6 +138,7 @@ def #{name}( raw = false )
         EOF
       end
 
+      # @private
       def build_validators
         if @klass.included_modules.include?( ::CouchRest::Validation )
 
@@ -81,6 +148,7 @@ def build_validators
         end
       end
 
+      # @private
       def build_views
         @klass.view_by :rel,
           :map => <<-MAP