resource.rb in trust-0.7.0

- old
+ new

@@ -59,11 +59,12 @@
       def instance
         @controller.instance_variable_get(:"@#{instance_name}")
       end
       
       # Sets the instance variable
-      # Normally set by +load+
+      #
+      # Normally set by +load+.
       # You can access this method from the resource object.
       #
       # ==== Example
       #
       #    resource.instance = Account.find_by_number(123456)
@@ -95,28 +96,32 @@
       def instances
         @controller.instance_variable_get(:"@#{plural_instance_name}")
       end
 
       # Sets the instance variable for collection
+      #
       # You may want to set this variable in your index action, we do not yet support loading of collections
       def instances=(instances)
         @controller.instance_variable_set(:"@#{plural_instance_name}", instances)
       end
 
       # Returns either the instances or the instance. 
+      #
       # We have found that this can be useful in some implementation patterns
       def instantiated
         instances || instance
       end
 
       # Returns the class for the resource
       def klass
         info.klass
       end
 
-      # Loads the resource 
+      # Loads the resource
+      #
       # See Trust::Controller::Properties which controls the behavior of this method.
+      #
       # It will normally find the instance variable for existing object or initialize them as new.
       # If using nested resources and +belongs_to+ has been declared in the controller it will use the 
       # parent relation if found.
       def load
         self.parent = parent_info.object if parent_info
@@ -132,28 +137,31 @@
 #          logger.debug "Trust.load: Parent is: #{parent.inspect}, collection or unknown action."
         end 
       end
       
       # Returns the name of the instance for the resource
+      #
       # ==== Example
       #
       #     # in AccountsController
       #     resource.instance_name  # => :account
       def instance_name
         info.name
       end
       
       # Returns the plural name of the instance for the resource
+      #
       # ==== Example
       #
       #     # in AccountsController
       #     resource.plural_instance_name  # => :accounts
       def plural_instance_name
         info.plural_name
       end
       
       # Returns the name of the parent resource
+      #
       # ==== Example
       #
       #     # in AccountsController where belongs_to :customer has been declared
       #     resource.parent_name  # => :customer
       def parent_name
@@ -169,80 +177,88 @@
       def extract_parent_info(associations, params, request) #nodoc
         ParentInfo.new(associations, params, request)
       end      
     end
 
-    # ResorceInfo resolves information about the resource accessed in action controller
+    # = ResorceInfo 
     #
-    # Examples in PeopleController (simple case)
-    # ===
+    # resolves information about the resource accessed in action controller
+    #
+    # === Examples in PeopleController (simple case)
+    # 
     #   resource.info.klass => Person
     #   resource.info.params => {:person => {...}}       # fetches the parameters for the resource
     #   resource.info.name => :person
     #   resource.info.plural_name => :people
     #   resource.info.path => 'people'                   # this is the controller_path
     #
-    # Examples in Lottery::AssignmentsController (with name space)
-    # ===
+    # === Examples in Lottery::AssignmentsController (with name space)
+    # 
     #   resource.info.klass => Lottery::Assignment
     #   resource.info.params => {:lottery_assignment => {...}}
     #   resource.info.name => :lottery_assignment
     #   resource.info.plural_name => :lottery_assignments
     #   resource.info.path => 'lottery/assignments'      # this is the controller_path
     #
-    # Examples in ArchiveController (with inheritance) 
+    # === Examples in ArchiveController (with inheritance) 
     # Assumptions on routes:
+    #
     #   resources :archives
     #   resources :secret_acrvives, :controller => :archives
     #   resources :public_acrvives, :controller => :archives
-    # examples below assumes that the route secret_arcives is being accessed at the moment
-    # ===
+    #
+    # === Examples below assumes that the route secret_arcives is being accessed at the moment
+    # 
     #   resource.info.klass => Archive
     #   resource.info.params => {:secret_archive => {...}}
     #   resource.info.name => :archive
     #   resource.info.plural_name => :archives
     #   resource.info.path => 'archive'                   # this is the controller_path
     #   resource.info.real_class => SecretArchive         # Returns the real class which is accessed at the moment
     #
-    
     class Resource::Info
       attr_reader :klass, :params, :name, :path, :real_class
       
-      def params
+      def params #:nodoc:
         @data
       end
    
     protected
-      def self.var_name(klass)
+      def self.var_name(klass)  #:nodoc:
         klass.to_s.underscore.tr('/','_').to_sym
       end
-      def var_name(klass)
+      def var_name(klass)  #:nodoc:
         self.class.var_name(klass)
       end
     end
     
-
+    # = Resource::ResorceInfo 
+    # 
+    # Resolves the resource in subject
+    # (see #ResourceInfo)
     class Resource::ResourceInfo < Resource::Info
 
-      def initialize(model, params)
+      def initialize(model, params)  #:nodoc:
         @path, params = model, params
         @klass = model.to_s.classify.constantize
         @name = model.to_s.singularize.underscore.gsub('/','_').to_sym
         ptr = @klass.descendants.detect do |c|
           params.key? var_name(c)
         end || @klass
         @real_class = ptr
         @data = params[var_name(ptr)]
       end
 
+      # Returns the plural name of the resource
       def plural_name
         @plural_name ||= path.underscore.tr('/','_').to_sym
       end
 
-      # returns an accessor for association. Tries with full name association first, and if that does not match, tries the demodularized association.
+      # Returns an accessor for association. Tries with full name association first, and if that does not match, tries the demodularized association.
       #
-      # Explanation:
+      # === Explanation
+      #
       #   Assuming 
       #     resource is instance of Lottery::Package #1 (@lottery_package)
       #     association is Lottery::Prizes
       #     if association is named lottery_prizes, then that association is returned
       #     if association is named prizes, then that association is returned
@@ -256,9 +272,13 @@
           klass
         end
       end
     end
 
+    # = Resource::ParentInfo 
+    # 
+    # Resolves the parent resource in subject
+    # (see #ResourceInfo)
     class Resource::ParentInfo < Resource::Info
       attr_reader :object,:as
       def initialize(resources, params, request)
         ptr = resources.detect do |r,as|
           @klass = classify(r)