From a423dd1f585375c79e79ca19e52dba322cd38eba Mon Sep 17 00:00:00 2001
From: Joachim Filip Ignacy Bartosik <jbartosik@gmail.com>
Date: Fri, 13 Aug 2010 18:35:31 +0200
Subject: Document modules

Permissions and RichTypes
---
 lib/permissions/anyone_can_view_admin_can_change.rb     |  3 +++
 lib/permissions/anyone_can_view_recruiter_can_change.rb |  2 ++
 lib/permissions/inherit.rb                              |  2 ++
 lib/permissions/owned_model.rb                          | 15 +++++++++++----
 lib/permissions/set.rb                                  |  5 +++++
 lib/rich_types/check_list.rb                            |  1 +
 6 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/lib/permissions/anyone_can_view_admin_can_change.rb b/lib/permissions/anyone_can_view_admin_can_change.rb
index dcfeb0a..f323a51 100644
--- a/lib/permissions/anyone_can_view_admin_can_change.rb
+++ b/lib/permissions/anyone_can_view_admin_can_change.rb
@@ -1,5 +1,8 @@
 require 'permissions/set'
+# Modules helping to manage permissions
 module Permissions
+  # If you include this administrators will be allowed to do everything,
+  # others users will will be able only to view.
   module AnyoneCanViewAdminCanChange
     multi_permission :create, :update, :destroy do
       acting_user.administrator?
diff --git a/lib/permissions/anyone_can_view_recruiter_can_change.rb b/lib/permissions/anyone_can_view_recruiter_can_change.rb
index 1faa96f..89984a9 100644
--- a/lib/permissions/anyone_can_view_recruiter_can_change.rb
+++ b/lib/permissions/anyone_can_view_recruiter_can_change.rb
@@ -1,5 +1,7 @@
 require 'permissions/set'
 module Permissions
+  # If you include this recruiters will be allowed to do everything,
+  # others users will will be able only to view.
   module AnyoneCanViewRecruiterCanChange
     multi_permission :create, :update, :destroy do
       User.user_is_recruiter?(acting_user)
diff --git a/lib/permissions/inherit.rb b/lib/permissions/inherit.rb
index fa35a0a..2617d82 100644
--- a/lib/permissions/inherit.rb
+++ b/lib/permissions/inherit.rb
@@ -1,4 +1,6 @@
 require 'permissions/set.rb'
+# If you call this in your model it will have exactly the same permissions as
+# source.
 def inherit_permissions(source)
   one_permission(:view){ send(source).nil? || send(source).send("viewable_by?", acting_user)}
   one_permission(:create){ send(source).nil? || send(source).send("creatable_by?", acting_user)}
diff --git a/lib/permissions/owned_model.rb b/lib/permissions/owned_model.rb
index e12706d..695add7 100644
--- a/lib/permissions/owned_model.rb
+++ b/lib/permissions/owned_model.rb
@@ -1,4 +1,5 @@
 module Permissions
+  # Please don't include this directly - use owned_model method
   module OwnedModel
     def create_permitted?
       acting_user.signed_up?
@@ -7,7 +8,7 @@ module Permissions
     def update_permitted?
       owned?
     end
-  
+
     def edit_permitted?(field)
      owned_soft?
     end
@@ -24,11 +25,11 @@ module Permissions
       def owned?
         owner_is?(acting_user) and !owner_changed?
       end
-    
+
       def owned_soft?
         owner_is?(acting_user)
       end
-    
+
       def must_be_owned
         errors.add(:owner, "must be current_user") unless owned?
       end
@@ -38,7 +39,13 @@ module Permissions
       end
   end
 end
-  
+
+# If you use this in your model it will have two effects:
+# - It will add belong_to owner relation with :creator => true. Owner will be
+#   read only, never shown attribute.
+# - It will set permissions so any signed up user will be able to create,
+#   update, destroy, view and edit owned instance of model. No one else will
+#   be able to.
 def owned_model(owner_class)
   belongs_to    :owner, :class_name => owner_class, :creator => true
   never_show    :owner
diff --git a/lib/permissions/set.rb b/lib/permissions/set.rb
index 14c93ef..0038995 100644
--- a/lib/permissions/set.rb
+++ b/lib/permissions/set.rb
@@ -1,13 +1,18 @@
 AllPermissions = [:create, :update, :destroy, :view, :edit]
 
+# Block will be used to determine chosen permission
 def one_permission(permission,  &block)
     define_method("#{permission.to_s}_permitted?", &block)
 end
+
+# Block will be used to determine chosen permissions
 def multi_permission(*permission_list,  &block)
   permission_list.flatten.each do |target|
     one_permission(target, &block)
   end
 end
+
+# Block will be used to determine all permission
 def single_permission(&block)
   multi_permission(AllPermissions, &block)
 end
diff --git a/lib/rich_types/check_list.rb b/lib/rich_types/check_list.rb
index 57510a6..5b948fa 100644
--- a/lib/rich_types/check_list.rb
+++ b/lib/rich_types/check_list.rb
@@ -1,3 +1,4 @@
+# This module includes non-basic types used in models
 module RichTypes
   # Stores information on which options were selected.
   # Use options and options= methods to access & set information on which are selected.
-- 
cgit v1.2.3-65-gdbad