Added some RDoc documentation for some models.

Submitted by austenito on Github.

git-svn-id: svn+ssh://rubyforge.org/var/svn/redmine/trunk@2612 e93f8b46-1217-0410-a6f0-8f06a7374b81

diff --git a/app/models/issue.rb b/app/models/issue.rb
index 4e2a3c6470b2c91bd7974ff69c5b28d29bc2a7cb..f3513e564f91f5fb6cce864120a7cd2942516e60 100644 (file)
--- a/app/models/issue.rb
+++ b/app/models/issue.rb
@@ -241,6 +241,11 @@ class Issue < ActiveRecord::Base
     recipients.compact.uniq
   end
   
+  # Returns the total number of hours spent on this issue.
+  #
+  # Example:
+  #   spent_hours => 0
+  #   spent_hours => 50
   def spent_hours
     @spent_hours ||= time_entries.sum(:hours) || 0
   end
@@ -269,6 +274,11 @@ class Issue < ActiveRecord::Base
     due_date || (fixed_version ? fixed_version.effective_date : nil)
   end
   
+  # Returns the time scheduled for this issue.
+  # 
+  # Example:
+  #   Start Date: 2/26/09, End Date: 3/04/09
+  #   duration => 6
   def duration
     (start_date && due_date) ? due_date - start_date : 0
   end

diff --git a/app/models/mailer.rb b/app/models/mailer.rb
index c348adf13bd4fe122de27321428086236e83408a..560f2cb6fb1b210d6afed1e560d162b849700039 100644 (file)
--- a/app/models/mailer.rb
+++ b/app/models/mailer.rb
@@ -29,6 +29,11 @@ class Mailer < ActionMailer::Base
     { :host => h, :protocol => Setting.protocol }
   end
   
+  # Builds a tmail object used to email recipients of the added issue.
+  #
+  # Example:
+  #   issue_add(issue) => tmail object
+  #   Mailer.deliver_issue_add(issue) => sends an email to issue recipients
   def issue_add(issue)
     redmine_headers 'Project' => issue.project.identifier,
                     'Issue-Id' => issue.id,
@@ -42,6 +47,11 @@ class Mailer < ActionMailer::Base
          :issue_url => url_for(:controller => 'issues', :action => 'show', :id => issue)
   end
 
+  # Builds a tmail object used to email recipients of the edited issue.
+  #
+  # Example:
+  #   issue_edit(journal) => tmail object
+  #   Mailer.deliver_issue_edit(journal) => sends an email to issue recipients
   def issue_edit(journal)
     issue = journal.journalized
     redmine_headers 'Project' => issue.project.identifier,
@@ -72,6 +82,11 @@ class Mailer < ActionMailer::Base
          :issues_url => url_for(:controller => 'issues', :action => 'index', :set_filter => 1, :assigned_to_id => user.id, :sort_key => 'due_date', :sort_order => 'asc')
   end
 
+  # Builds a tmail object used to email users belonging to the added document's project.
+  #
+  # Example:
+  #   document_added(document) => tmail object
+  #   Mailer.deliver_document_added(document) => sends an email to the document's project recipients
   def document_added(document)
     redmine_headers 'Project' => document.project.identifier
     recipients document.project.recipients
@@ -80,6 +95,11 @@ class Mailer < ActionMailer::Base
          :document_url => url_for(:controller => 'documents', :action => 'show', :id => document)
   end
 
+  # Builds a tmail object used to email recipients of a project when an attachements are added.
+  #
+  # Example:
+  #   attachments_added(attachments) => tmail object
+  #   Mailer.deliver_attachments_added(attachments) => sends an email to the project's recipients
   def attachments_added(attachments)
     container = attachments.first.container
     added_to = ''
@@ -102,7 +122,12 @@ class Mailer < ActionMailer::Base
          :added_to => added_to,
          :added_to_url => added_to_url
   end
-
+  
+  # Builds a tmail object used to email recipients of a news' project when a news item is added.
+  #
+  # Example:
+  #   news_added(news) => tmail object
+  #   Mailer.deliver_news_added(news) => sends an email to the news' project recipients
   def news_added(news)
     redmine_headers 'Project' => news.project.identifier
     message_id news
@@ -112,6 +137,11 @@ class Mailer < ActionMailer::Base
          :news_url => url_for(:controller => 'news', :action => 'show', :id => news)
   end
 
+  # Builds a tmail object used to email the specified recipients of the specified message that was posted. 
+  #
+  # Example:
+  #   message_posted(message, recipients) => tmail object
+  #   Mailer.deliver_message_posted(message, recipients) => sends an email to the recipients
   def message_posted(message, recipients)
     redmine_headers 'Project' => message.project.identifier,
                     'Topic-Id' => (message.parent_id || message.id)
@@ -123,6 +153,11 @@ class Mailer < ActionMailer::Base
          :message_url => url_for(:controller => 'messages', :action => 'show', :board_id => message.board_id, :id => message.root)
   end
 
+  # Builds a tmail object used to email the specified user their account information.
+  #
+  # Example:
+  #   account_information(user, password) => tmail object
+  #   Mailer.deliver_account_information(user, password) => sends account information to the user
   def account_information(user, password)
     set_language_if_valid user.language
     recipients user.mail
@@ -132,6 +167,11 @@ class Mailer < ActionMailer::Base
          :login_url => url_for(:controller => 'account', :action => 'login')
   end
 
+  # Builds a tmail object used to email all active administrators of an account activation request.
+  #
+  # Example:
+  #   account_activation_request(user) => tmail object
+  #   Mailer.deliver_account_activation_request(user)=> sends an email to all active administrators
   def account_activation_request(user)
     # Send the email to all active administrators
     recipients User.active.find(:all, :conditions => {:admin => true}).collect { |u| u.mail }.compact
@@ -140,7 +180,11 @@ class Mailer < ActionMailer::Base
          :url => url_for(:controller => 'users', :action => 'index', :status => User::STATUS_REGISTERED, :sort_key => 'created_on', :sort_order => 'desc')
   end
 
-  # A registered user's account was activated by an administrator
+  # Builds a tmail object used to email the specified user that their account was activated by an administrator.
+  #
+  # Example:
+  #   account_activated(user) => tmail object
+  #   Mailer.deliver_account_activated(user) => sends an email to the registered user
   def account_activated(user)
     set_language_if_valid user.language
     recipients user.mail

diff --git a/app/models/project.rb b/app/models/project.rb
index 980d194b100e73586c9493faa47f3897763d6f17..5778966e767a1f47dafa08d6a2ded38b6bf5b4b0 100644 (file)
--- a/app/models/project.rb
+++ b/app/models/project.rb
@@ -99,6 +99,11 @@ class Project < ActiveRecord::Base
     find(:all, :limit => count, :conditions => visible_by(user), :order => "created_on DESC")  
   end  
 
+  # Returns a SQL :conditions string used to find all active projects for the specified user.
+  #
+  # Examples:
+  #     Projects.visible_by(admin)        => "projects.status = 1"
+  #     Projects.visible_by(normal_user)  => "projects.status = 1 AND projects.is_public = 1"
   def self.visible_by(user=nil)
     user ||= User.current
     if user && user.admin?
@@ -141,7 +146,12 @@ class Project < ActiveRecord::Base
     end
     statements.empty? ? base_statement : "((#{base_statement}) AND (#{statements.join(' OR ')}))"
   end
-  
+
+  # Returns a :conditions SQL string that can be used to find the issues associated with this project.
+  #
+  # Examples:
+  #   project.project_condition(true)  => "(projects.id = 1 OR (projects.lft > 1 AND projects.rgt < 10))"
+  #   project.project_condition(false) => "projects.id = 1"
   def project_condition(with_subprojects)
     cond = "#{Project.table_name}.id = #{id}"
     cond = "(#{cond} OR (#{Project.table_name}.lft > #{lft} AND #{Project.table_name}.rgt < #{rgt}))" if with_subprojects
@@ -273,6 +283,10 @@ class Project < ActiveRecord::Base
     description.gsub(/^(.{#{length}}[^\n\r]*).*$/m, '\1...').strip if description
   end
   
+  # Return true if this project is allowed to do the specified action.
+  # action can be:
+  # * a parameter-like Hash (eg. :controller => 'projects', :action => 'edit')
+  # * a permission Symbol (eg. :edit_project)
   def allows_to?(action)
     if action.is_a? Hash
       allowed_actions.include? "#{action[:controller]}/#{action[:action]}"

diff --git a/app/models/user.rb b/app/models/user.rb
index f42787f5d0e219714a128157b1ab879ace948f7e..63393a6d537d6d81719a7818ebfe70805a166a09 100644 (file)
--- a/app/models/user.rb
+++ b/app/models/user.rb
@@ -286,6 +286,8 @@ class User < ActiveRecord::Base
     @current_user ||= User.anonymous
   end
   
+  # Returns the anonymous user.  If the anonymous user does not exist, it is created.  There can be only
+  # one anonymous user per database.
   def self.anonymous
     anonymous_user = AnonymousUser.find(:first)
     if anonymous_user.nil?

diff --git a/app/models/version.rb b/app/models/version.rb
index 679854340d50b54bd4a92247a88dec2f697deea8..13d33e256a4938dd99e18b756cebf56e78047441 100644 (file)
--- a/app/models/version.rb
+++ b/app/models/version.rb
@@ -50,6 +50,8 @@ class Version < ActiveRecord::Base
     effective_date && (effective_date <= Date.today) && (open_issues_count == 0)
   end
   
+  # Returns the completion percentage of this version based on the amount of open/closed issues
+  # and the time spent on the open issues.
   def completed_pourcent
     if issues_count == 0
       0
@@ -60,6 +62,7 @@ class Version < ActiveRecord::Base
     end
   end
   
+  # Returns the percentage of issues that have been marked as 'closed'.
   def closed_pourcent
     if issues_count == 0
       0
@@ -78,10 +81,12 @@ class Version < ActiveRecord::Base
     @issue_count ||= fixed_issues.count
   end
   
+  # Returns the total amount of open issues for this version.
   def open_issues_count
     @open_issues_count ||= Issue.count(:all, :conditions => ["fixed_version_id = ? AND is_closed = ?", self.id, false], :include => :status)
   end
 
+  # Returns the total amount of closed issues for this version.
   def closed_issues_count
     @closed_issues_count ||= Issue.count(:all, :conditions => ["fixed_version_id = ? AND is_closed = ?", self.id, true], :include => :status)
   end
@@ -124,17 +129,22 @@ private
     @estimated_average
   end
   
-  # Returns the total progress of open or closed issues
+  # Returns the total progress of open or closed issues.  The returned percentage takes into account
+  # the amount of estimated time set for this version.
+  #
+  # Examples:
+  # issues_progress(true)   => returns the progress percentage for open issues.
+  # issues_progress(false)  => returns the progress percentage for closed issues.
   def issues_progress(open)
     @issues_progress ||= {}
     @issues_progress[open] ||= begin
       progress = 0
       if issues_count > 0
         ratio = open ? 'done_ratio' : 100
+        
         done = fixed_issues.sum("COALESCE(estimated_hours, #{estimated_average}) * #{ratio}",
                                   :include => :status,
                                   :conditions => ["is_closed = ?", !open]).to_f
-                                  
         progress = done / (estimated_average * issues_count)
       end
       progress