From c2dfffd7f267b2064bb51d46aac6fb1429b37132 Mon Sep 17 00:00:00 2001 From: Eric Davis Date: Sat, 21 Mar 2009 00:39:53 +0000 Subject: [PATCH] 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 --- app/models/issue.rb | 10 +++++++++ app/models/mailer.rb | 48 +++++++++++++++++++++++++++++++++++++++++-- app/models/project.rb | 16 ++++++++++++++- app/models/user.rb | 2 ++ app/models/version.rb | 14 +++++++++++-- 5 files changed, 85 insertions(+), 5 deletions(-) diff --git a/app/models/issue.rb b/app/models/issue.rb index 4e2a3c647..f3513e564 100644 --- 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 c348adf13..560f2cb6f 100644 --- 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 980d194b1..5778966e7 100644 --- 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 f42787f5d..63393a6d5 100644 --- 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 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