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

1 files changed, 12 insertions, 2 deletions

diff --git a/app/models/version.rb b/app/models/version.rb
index 679854340..13d33e256 100644
--- 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