Adding some docs.

MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Action Moniker LLC., http://www.actionmoniker.com/
+Copyright (c) 2008 Ken Collins, Decisiv Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.rdoc

@@ -1,27 +1,78 @@
 
-GroupedScope
-============
+== GroupedScope: Has Many Associations IN (GROUPS)
 
-Introduction goes here.
+GroupedScope aims to make two things easier in your ActiveRecord models. First, provide a 
+easy way to group objects, second, to allow the group to share associated object via existing 
+has_many relationships. See installation and usage for more details.
 
 
-TODO
-====
+=== Installation & Usage
 
-* Raise error if piggy back assoc uses :finder_sql option
-* Change these to account for :as option:
-  GroupedScope::HasManyAssociation
-* Turn on some mocha options/warnings.
-* Support finder sql
+From your project's RAILS_ROOT, run:
 
-Running Tests
-=============
+  script/plugin install git://github.com/metaskills/grouped_scope.git
 
-Make sure to install
-require 'shoulda'
-require 'mocha'
+To use GroupedScope on a model it must have a :group_id column.
 
+  class AddGroupId < ActiveRecord::Migration
+    def self.up
+      add_column :employees, :group_id, :integer
+    end
+    def self.down
+      remove_column :employees, :group_id
+    end
+  end
 
-Copyright (c) 2008 Action Moniker LLC., http://www.actionmoniker.com/ 
+Assume the following model.
+
+  class Employee < ActiveRecord::Base
+    has_many :reports
+    grouped_scope :reports
+  end
+
+By calling grouped_scope on any association you create a new group accessor for each 
+instance. The object returned will act just like an array and at least include the 
+current object that called it.
+
+  @employee_one.group   # => [#<Employee id: 1, group_id: nil>]
+
+To group resources, just assign the same :group_id in the schema. Note that in future 
+versions I will be extending the GroupedScope::Grouping that each object belongs to. 
+If you do not just want to assign some random integers, then take a look at that model 
+and the belongs_to :grouping code, schema needed ofcourse
+
+  @employee_one.update_attribute :group_id, 1
+  @employee_two.update_attribute :group_id, 1
+  @employee_one.group   # => [#<Employee id: 1, group_id: 1>, #<Employee id: 2, group_id: 1>]
+
+Calling grouped_scope on the :reports association leaves the existing association intact.
+
+  @employee_one.reports  # => [#<Report id: 2, employee_id: 1>]
+  @employee_two.reports  # => [#<Report id: 18, employee_id: 2>, #<Report id: 36, employee_id: 2>]
+
+Now the good part, all associations passed to the grouped_scope method can be called 
+on the group proxy. The collection will return resources shared by the group.
+
+  @employee_one.group.reports   # => [#<Report id: 2, employee_id: 1>, 
+                                      #<Report id: 18, employee_id: 2>, 
+                                      #<Report id: 36, employee_id: 2>]
+
+You can even call named scopes defined on the objects in the collection and association 
+extensions defined on the original has_many. For instance:
+
+  @employee.group.reports.urgent.assigned_to(user)
+
+
+
+=== Todo List
+
+* Add more GroupedScope::Grouping code.
+* Add polymorphic support.
+* Add/test has_and_belongs_to_many
+* Raise errors and/or support :finder_sql/:counter_sql.
+* Add a user definable group_id schema.
+
+
+Copyright (c) 2008 Ken Collins, Decisiv Inc.
 Released under the MIT license.
 

lib/grouped_scope.rb

@@ -8,7 +8,7 @@
 
 module GroupedScope
 
-  VERSION = '1.0.0'
+  VERSION = '0.1.0'
 
 end